ابزار سایت

معرفی_کلاس_ها_و_توابع_مهم_در_موتوشاب

فهرست مندرجات

فصل 6- معرفی کلاس‌ها و توابع مهم در موتوشاب

در این بخش به شرح و معرفی کلاس‌ها و توابع مهم در موتوشاب پرداخته شده است. این بخش در حقیقت مرجع توسعه‌دهندگان موتوشاب برای فراگیری قابلیت‌هایی است که هسته موتوشاب در اختیار آن‌ها قرار داده است.

6-1- OW_EventManager

از کلاس مذکور برای مدیریت رویدادهای سامانه استفاده می‌شود. برای مثال رویداد ورود کاربر به سامانه (با وارد نمودن نام کاربری و رمز ‌عبور خود) و یا رویداد خروج کاربر از سامانه و غیره در این کلاس مدیریت می‌شود.

6-1-1- bind

با استفاده از این تابع، می‌توان یک تابع را به یک رویداد الصاق کرد. در این صورت هنگام رخداد رویداد مذکور، تابع مذکور نیز فراخوانی می‌شود. برای مثال در کد زیر:

OW::getEventManager()->bind(IISEventManager::ON_BEFORE_VALIDATING_FIELD, array($this, 'onBeforeValidatingField'));

تابع onBeforeValidatingField به رویداد IISEventManager::ON_BEFORE_VALIDATING_FIELD الصاق شده است. در این صورت هنگام رخداد این رویداد، تابع مذکور فراخوانی خواهد شد. تابع bind دارای سه ورودی بوده که عبارت‌اند از نام رویداد تعریف‌شده ($name)، نام تابع ($callback) و اولویت اجرای تابع ($priority).

6-1-2- trigger

این تابع یک ورودی از نوع رویداد (OW_Event) گرفته و آن را اجرا می‌کند.

$yearChangedEvent = OW::getEventManager()->trigger(new OW_Event(IISEventManager::ON_BEFORE_VALIDATING_FIELD, array('field' => $element, 'data' => $data)));

کد بالا تابع الصاق شده به رویداد ON_BEFORE_VALIDATING_FIELD را با پارامترهای ورودی مربوط به رویداد اجرا می‌کند. در بخش بعد بیشتر درباره کلاس OW_Event و پارامترهای ورودی آن توضیح داده خواهد شد.

6-2- OW_Event

توابع اصلی و پایه‌ای یک رویداد در این کلاس تعریف شده است. توابع مهم این کلاس در ادامه توضیح داده شده‌است:

6-2-1- تابع سازنده

تابع سازنده OW_Event به شرح زیر است:

public function __construct( $name, array $params = array(), $dataValue = null )

name$ نام رویداد، params$ آرایه‌ای از پارامترهای ورودی و dataValue$ نیز داده‌های پردازش‌شده ارسالی به خروجی است.

نکته: توابع set و get مربوط به سه پارامتر ورودی تابع بالا در کلاس مذکور تعریف شده‌اند. برای مثال شبه کد زیر:

OW_Event $event;
$params = $event->getParams();

پارامترهای داده‌شده ‌(params$) به رویداد مورد نظر را برمی‌گرداند.

6-3- OW_CONFIG

هدف از این کلاس کار با تنظیمات سیستمی موتوشاب است که عموما در جدول ow_base_config ذخیره شده‌اند. در ادامه به توابع مهم این کلاس اشاره شده است.

6-3-1- generateCache

از این تابع برای سپردن کلیه تنظیمات سیستم (جدول ow_base_config) به حافظه نهان به منظور افزایش سرعت و کارایی استفاده می‌شود.

نکته: به طور کلی پس از هر بار تغییر در جدول ow_base_config با فراخوانی توابع حذف، ایجاد و یا به‌روزرسانی (که در ادامه به توضیح مفصل این توابع پرداخته شده است)، این تابع به صورت خودکار در انتهای توابع مذکور فراخوانی می‌شود. در نتیجه توسعه‌دهنده در اغلب موارد نیازی به استفاده از این تابع ندارد.

6-3-2- addConfig

هدف از این تابع اضافه‌کردن تنظیمات جدید به تنظیمات موجود در جدول ow_base_config است. تابع مذکور به ترتیب چهار ورودی نام افزونه ($key)، نام تنظیم مورد نظر ($name)، مقدار تنظیم ($value) و توضیحات مربوط به تنظیم ($description) که اختیاری بوده را دارا است. به عنوان مثال:

$config = OW::getConfig();
$config->addConfig('iisjalali', 'dateLocale',1);

برای افزونه iisjalali تنظیم dateLocale مقدار 1 را وارد جدول بالا می‌کند. در نتیجه همان‌طور که مشخص است برای هر تنظیم می‌بایست نام افزونه مرتبط با آن نیز مشخص شود.

6-3-3- deleteConfig

هدف از این تابع حذف نمودن تنظیمی از تنظیمات موجود در جدول ow_base_config است. این تابع دو ورودی به ترتیب نام افزونه ($key) و نام تنظیم مورد نظر ($name) را گرفته و تنظیم مورد نظر را حذف می‌کند. به عنوان مثال:

OW::getConfig()->deleteConfig('mailbox', 'results_per_page');

برای افزونه mailbox تنظیم results_per_page را از جدول ow_base_config حذف می‌کند.

6-3-4- getValue و getValues

هدف از این توابع استخراج نمودن تنظیمی‌ (تنظیماتی) از تنظیمات موجود در جدول ow_base_config است. برای مثال تابع getValue با گرفتن دو پارامتر ورودی نام افزونه ($key) و نام تنظیم ($name) مقدار تنظیم انجام شده را بر می-گرداند. مثال:

OW::getConfig()->getValue('iisjalali', 'dateLocale')

6-3-5- configExists

هدف از این تابع بررسی وجود تنظیمی از بین تنظیمات موجود در جدول ow_base_config است که به ترتیب دو ورودی نام افزونه ($key)، نام تنظیم مورد نظر ($name) را گرفته و موجودیت تنظیم مورد نظر را بررسی می‌کند.

مثال کد زیر در صورت عدم وجود تنظیم dateLocale آن را اضافه می‌کند.

if ( !$config->configExists('iisjalali', 'dateLocale') )
{
    $config->addConfig('iisjalali', 'dateLocale',1);
}

6-3-6- saveConfig

هدف از این تابع به‌روزرسانی تنظیم مورد نظر در جدول ow_base_config است.‌ تفاوت اصلی این تابع با تابع addConfig این است که در saveConfig هدف تنها به‌روزرسانی تنظیم مورد نظر است که حتما می‌بایست از قبل وجود داشته باشد و در صورت عدم وجود پیغام خطا نمایش داده می‌شود. این تابع به ترتیب سه ورودی نام افزونه ($key)، نام تنظیم مورد نظر ($name) و مقدار تنظیم ($value) را گرفته و به‌روزرسانی را انجام می‌دهد.

$config->saveConfig('iisjalali', 'dateLocale', $form->getElement('dateLocale')->getValue())

کد بالا تنظیم dateLocale مربوط به افزونه iisjalali را به‌روزرسانی می‌کند.

بسیاری از توابع کاربردی موتوشاب در این کلاس تعریف می‌شوند.

6-4-1- getConfig

این تابع یک شیء از کلاس Config که شامل تنظیمات موجود در جدول ow_base_config است را ساخته و ارائه می‌کند.

$config = OW::getConfig();

در حقیقت این کلاس واسط ارتباطی با جدول ow_base_config و تمامی تنظیمات سامانه است.

6-4-2- getSession

یک نمونه از کلاس Session که شامل تنظیمات مربوط به نشست بوده را ساخته و بر می‌گرداند. در حقیقت شیء برگردانده‌شده واسط ارتباطی با نشست کاربر است.

6-4-3- getUser

یک نمونه از کلاس User که مربوط به کاربر فعلی را ساخته و ارائه می‌کند.

6-4-4- getDbo

دسترسی به پایگاه داده با تنظیمات پیش‌فرض با استفاده از فراخوانی این تابع انجام می‌شود. کاربرد بسیار مهم این تابع در هنگام نصب افزونه‌ها برای ایجاد جداول لازم برای آن‌ها در فایل install.php این افزونه‌ها است؛ مانند کد زیر برای ایجاد جدول برای افزونه تولد:

OW::getDbo()->query("
CREATE TABLE IF NOT EXISTS `" . OW_DB_PREFIX . "birthdays_privacy` (
  `id` int(11) NOT NULL auto_increment,
  `userId` int(11) NOT NULL,
  `privacy` varchar(32) NOT NULL,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `userId` (`userId`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;");

6-4-5- getLanguage

یک نمونه از کلاس Language که مربوط به تنظیمات زبان سامانه است را ساخته و ارائه می‌کند.

6-4-6- getPluginManager

یک نمونه از کلاس Plugin Manager که مربوط به مدیریت افزونه‌های سامانه است را ساخته و ارائه می‌کند.

6-4-7- geThemeManager

یک نمونه از کلاس ThemeManager که مربوط به مدیریت تصاویر پس‌زمینه و نمای گرافیکی سامانه است را ساخته و ارائه می‌کند.

6-4-8- getEventManager

یک نمونه از کلاس Event Manager که مربوط به مدیریت رویدادهای سامانه است را ساخته و ارائه می‌کند.

6-4-9- getRouter

یک نمونه از کلاس Router که مسئول یافتن کنترل‌کننده و عملیات مناسب است را ساخته و ارائه می‌کند.

6-4-10- تابع getRequest

یک نمونه از کلاس Request ساخته و ارائه می‌کند.

6-4-11- تابع getDocument

با استفاده از این تابع می‌توان به اجزای صفحه HTML سامانه دسترسی داشت. برای مثال عموما کدهای جاوااسکریپتی که برای افزونه‌ها نوشته می‌شود در مسیر ثابت static/js/{code_name.js} مربوط به آن افزونه قرار می‌گیرد، فایل مذکور به صورت زیر قابل دسترسی است:

$jsDir = OW::getPluginManager()->getPlugin('iisjalali')->getStaticJsUrl();
OW::getDocument()->addScript($jsDir.'iisjalali.js');

6-5- Language

با استفاده از این کلاس می‌توان به برخی توابع پرکاربرد مربوط به متون سامانه از قبیل واردسازی عبارت‌های لازم برای یک افزونه در سامانه، نمایش عبارات مورد نیاز برای استفاده در زبان جاوااسکریپت به آن منتقل نمود.

6-5-1- text

تابع مورد نظر سه ورودی عبارت از نام افزونه‌ای که متن می‌بایست از آن استخراج شود ($prefix) و همچنین نام متن مورد نظر ($key) و همچنین آرایه‌ای از پارامترهای ورودی پویا به متن برای نمایش ($vars) را گرفته و متن مورد نظر را نمایش می‌دهد. به عنوان مثال کد زیر متن مربوط به افزونه iisjalali با کلید date_locale_jalali_format را برمی‌گرداند.

OW::getLanguage()->text('iisjalali', 'date_locale_jalali_format')

6-5-2- valueExist

تابع فوق با گرفتن دو ورودی نام افزونه‌ای که متن می‌بایست از آن استخراج شود و همچنین نام متن مورد نظر، بررسی می-کند که آیا متن مورد نظر وجود دارد یا خیر. برای مثال:

if ( OW::getLanguage()->valueExist('base', "local_page_meta_tags_{$this->getDocumentKey()}") )
{
    OW::getDocument()->addCustomHeadInfo(OW::getLanguage()->text('base', "local_page_meta_tags_{$this->getDocumentKey()}"));
}

6-5-3- addKeyForJs

تابع فوق با گرفتن نام افزونه‌ای که متن می‌بایست از آن استخراج شود و همچنین نام متن مورد نظر، متن لازم را در هنگام بارگذاری برای استفاده کدهای جاوااسکریپت در اختیار آن قرار می‌دهد. برای مثال:

OW::getLanguage()->addKeyForJs('iispasswordstrengthmeter', 'strength_poor_label');

پس از فراخوانی کد بالا عبارت مربوط به افزونه iispasswordstremgthmeter با کلید strength_poor_label در جاوااسکریپت قابل استفاده است. نکته: فایل ow.js دارای توابعی برای استفاده از متون در جاوااسکریپت است. به عنوان مثال متناظر با تابع text از کلاس Language تابعی با نام getLanguageText نیز تعریف شده است؛ بنابراین خواندن تنظیم کد بالا در یک کد جاوااسکریپت و با استفاده از توابع ow.js به صورت زیر انجام می‌شود.

OW.getLanguageText('iispasswordstrengthmeter', 'strength_poor_label');

6-5-4- importPluginLangs

تابع فوق عموما در هنگام نصب افزونه‌های سامانه در فایل install.php مربوط به افزونه‌ و به منظور واردسازی عبارات زبان افزونه فراخوانی می‌شود مانند کد زیر که برای اضافه‌سازی زبان افزونه «birthdays» فراخوانی شده است:

OW::getLanguage()->importPluginLangs(OW::getPluginManager()-> getPlugin('birthdays')->getRootDir() . 'langs.zip', 'birthdays');

6-6- Router

کلیه مسیریابی‌ها از قبیل مسیریابی مربوط به کنترل‌کننده‌ها و یا عملیات‌ مورد نیاز در این کلاس تعریف می‌شوند.

6-6-1- سازنده

تابع سازنده پنج ورودی: نام مسیر، آدرس مسیر، نام کنترل‌کننده، نام تابع لازم برای تنظیمات اولیه‌ (همان تابع عملیات ) و آرایه‌ای از پارامترهای ورودی انتخابی را گرفته و مسیر مورد نظر را می‌سازد مانند کد زیر:

new OW_Route('iisjalali_admin_config', 'iisjalali/admin', 'IISJALALI_CTRL_Admin', 'index') 

6-6-2- addRoute

مسیر ساخته‌شده در قسمت قبل با استفاده از این تابع برای استفاده به router اضافه می‌شود:

OW::getRouter()->addRoute(new OW_Route('iisjalali_admin_config', 'iisjalali/admin', 'IISJALALI_CTRL_Admin', 'index'));

کلیه توابع لازم جهت نمایش فرم‌های موجود در سامانه که برای ورود اطلاعات از کاربران مورد استفاده قرار می‌گیرد، در این کلاس تعریف شده‌است.

6-7-1- سازنده Form

تابع فوق با گرفتن یک ورودی نام فرم مورد نظر، آن را ایجاد می‌کند.

6-7-2- setAjax

در صورتی که فرم مورد نظر به صورت Ajax باشد این تابع با مقدار true فراخوانی می‌شود‌‌، در غیر این صورت با مقدار false فراخوانی می‌شود.

6-7-3- setAjaxResetOnSuccess

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

6-7-4- setAction

با استفاده از این تابع مسیر و آدرس لازم برای خواندن تنظیمات انجام‌شده‌ (تمامی موارد ذکرشده در بالا و همچنین برخی تنظیمات دیگر) در اختیار فرم مورد نظر قرار می‌گیرد. به عنوان مثال:

$form->setAction(OW::getRouter()->urlForRoute('iisjalali_admin_config'));

6-7-5- bindJsFunction

این تابع نوع رویداد و یک تابع جاوااسکریپت را به عنوان ورودی گرفته و هنگام وقوع رویداد با نوع داده شده، تابع را اجرا می‌کند.

نکته 1: نوع رویداد به صورت متغیرهای ثابت در ابتدای کلاس Form تعریف شده است.

نکته2: تابع جاوااسکریپت را می‌توان در همان ورودی نیز نوشت؛ مانند کد زیر:

$form->bindJsFunction(Form::BIND_SUCCESS,'function( data ){ if(data && data.result){OW.info(\''.$language->text('iisjalali', 'settings_updated').'\')  }  }');

در صورتی که فرم با موفقیت ثبت شود و داده‌ای برگردانده شود، پیغام مربوط به افزونه iisjalali و کلید settings_updated نمایش داده می‌شود.

6-7-6- addElement

با استفاده از این تابع می‌توان به فرم مورد نظر فیلد اضافه کرد.

6-7-7- isValid

در صورتی که فیلد‌هایی از یک فرم نیاز به بررسی برای صحت داده‌های واردشده داشته باشد، بررسی صحت مقادیر با استفاده از این تابع انجام می‌شود. برای مثال ممکن است واردسازی مقدار یک المان اجباری باشد و یا داده یک المان باید به فرمت مشخصی وارد شود مثلا x-xxxx-xxx-xxxx-xx.

6-7-8- getElement

یک فیلد در فرم را می‌توان با این تابع دریافت نمود.

نکته: به طور کلی برای گرفتن مقدار یک فیلد در فرم از این تابع استفاده می‌شود مانند کد زیر:

$form->getElement('dateLocale')->getValue()

6-7-9- getValues

کلیه مقادیر موجود در المان‌های یک فرم را برمی‌گرداند.

6-7-10- getErrors

این تابع کلیه خطاهای یک فرم را برمی‌گرداند.

6-8- OW_Example

این کلاس به منظور استفاده هرچه آسان‌تر DAO از پرسمان‌های لازم برای پایگاه داده تعریف شده است.

6-8-1- andFieldEqual

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

public function getActiveUsers(){
    $ex = new OW_Example();
    $ex->andFieldEqual('lock', 0);
    return $this->findListByExample($ex);
}

کلیه کاربران فعال را برمی‌گرداند.

6-8-2- andFieldLike

این تابع دو ورودی گرفته؛ اولی نام فیلد مورد نظر و دومی مقدار مورد نظر است و با مقایسه مقدار مربوطه برای فیلد که شبیه باشد سطر مناسب را ارائه می‌کند. سایر توابع نیز مشابه توابع بالا پالایش‌های مربوط به پرسمان را پوشش می‌دهند.

نکته 1: توابع دیگری نیز مانند دو تابع ذکرشده در بالا وجود دارند که بسته به کاربرد می‌توانند فیلتر‌های دیگری را برای استخراج داده مورد نظر اعمال کنند.

نکته2: هر کلاس DAO که تعریف می‌شود از کلاس OW_BaseDao ارث می‌برد. در این کلاس چند تابع اصلی مربوط به اجرای کلاس Ow_Example نوشته شده که در ادامه به آن‌ها پرداخته شده است.

6-9- OW_BaseDao

هر کلاس DAO که تعریف می‌شود از کلاس OW_BaseDao ارث می‌برد. در این کلاس چند تابع اصلی قرار دارد.

6-9-1- findById

مقدار Id یک شیء موجودیت را گرفته و سطر متناظر با آن در جدول داده را در صورتی که وجود داشته باشد، برمی‌گرداند. به عنوان مثال:

public function findById( $id )
{
    $dao = $this->dao;
    return $dao->findById($id);
}

6-9-2- findByIdList

فهرستی از Id‌های موجودیت‌های یک نوع را گرفته و سطرهای متناظر با آن‌ها را در جدول پایگاه‌ داده در صورت وجود برمی-گرداند.

6-9-3- findListByExample

متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند. به عنوان مثال:

public function getActiveUsers(){
    $ex = new OW_Example();
    $ex->andFieldEqual('lock', 0);
    return $this->findListByExample($ex);
}

کد فوق فهرستی از کاربران که مقدار فیلد lock در آن‌ها صفر باشد را بر‌می‌گرداند.

6-9-4- save

برای ذخیره‌سازی یک موجودیت از این تابع استفاده می‌شود.

6-9-5- delete

برای حذف یک موجودیت از این تابع استفاده می‌شود.

6-9-6- findAll

کلیه داده‌های مربوط به یک جدول را برمی‌گرداند.

6-9-7- countAll

تعداد کل سطر‌های مربوط به یک جدول را برمی‌گرداند.

6-9-8- deleteByExample

این تابع متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود حذف می‌کند.

public function deleteByAuthorId( $userId )
{
    $ex = new OW_Example();
    $ex->andFieldEqual('authorId', $userId);
 
    $this->deleteByExample($ex);
}

6-9-9- countByExample

متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example تعداد سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند.

public function countFullsizePhotos()
{
    $example = new OW_Example();
    $example->andFieldEqual('hasFullsize', 1);
 
    return $this->countByExample($example);
}

کد فوق فهرستی از کاربران که مقدار فیلد lock در آن‌ها صفر باشد را بر‌می‌گرداند.

6-9-4- save

برای ذخیره‌سازی یک موجودیت از این تابع استفاده می‌شود.

6-9-5- delete

برای حذف یک موجودیت از این تابع استفاده می‌شود.

6-9-6- findAll

کلیه داده‌های مربوط به یک جدول را برمی‌گرداند.

6-9-7- countAll

تعداد کل سطر‌های مربوط به یک جدول را برمی‌گرداند.

6-9-8- deleteByExample

این تابع متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود حذف می‌کند

public function deleteByAuthorId( $userId )
{
    $ex = new OW_Example();
    $ex->andFieldEqual('authorId', $userId);
 
    $this->deleteByExample($ex);
}

6-9-9- countByExample

متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example تعداد سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند.

public function countFullsizePhotos()
{
    $example = new OW_Example();
    $example->andFieldEqual('hasFullsize', 1);
 
    return $this->countByExample($example);
}

6-10- OW_entity

به طور کلی تمامی موجودیت‌ها از کلاس پایه‌ای OW_Entity ارث می‌برند. کلاس مذکور دارای دو پارامتر اصلی با نام $Id و $_fieldsHash و چهار تابع اصلی به شرح ذیل است.

6-10-1- SetId و GetId

به ترتیب Setter و Getter مربوط به id موجودیت هستند. مقصود از موجودیت، جداول پایگاه داده و مقصود از $Id ستون Id این جداول است. شایان ذکر است که تمامی موجودیت‌ها در موتوشاب شناسه Id را به صورت پیش‌فرض دارند.

6-10-2- generateFieldsHash

برای ایجاد فیلدهای موجودیت مورد نظر‌(که عموما یکتا نیز می‌باشند) از این تابع استفاده می‌شود. نکته: دو تابع queryForObject و queryForObjectList مربوط به کلاس OW_Database از این تابع استفاده می‌کنند.

6-10-3- getEntinyUpdatedFields

کلیه فیلدهای مربوط به یک موجودیت که نیاز به به‌روزرسانی دارند با استفاده از این تابع و به صورت یک آرایه دریافت می-شوند. تابع updateObject مربوط به کلاس OW_Database از این آرایه استفاده می‌کند.

Ow_Entity $obj;
$fieldsToUpdate = $obj->getEntinyUpdatedFields ();

6-11- BOL_UserService

از این کلاس برای دسترسی به جدول مربوط به اطلاعات کاربران‌ (با استفاده از موجودیت‌های userDao، userOnlineDao، userSuspendDao و غیره که تمامی در تابع سازنده آن مقداردهی می‌شوند) استفاده می‌شود. این کلاس دارای توابع مختلفی است که در ادامه به مهم‌ترین آن‌ها اشاره شده است:

6-11-1- findUserForStandardAuth

تابع مذکور با گرفتن یک متغیر و جایگذاری آن به عنوان نام کاربری و یا ایمیل کاربر، او را در صورت یافتن برمی‌گرداند.

به عنوان مثال، تابع authenticate مربوط به کلاس BASE_CLASS_StandardAuth از تابع فوق برای بررسی صحت موجودیت افراد به عنوان کاربر استفاده می‌‌کند:

$user = $this->userService->findUserForStandardAuth($this->identity);
$language = OW::getLanguage();
if ( $user === null )
{
    return new OW_AuthResult(OW_AuthResult::FAILURE_IDENTITY_NOT_FOUND, null, array($language->text('base', 'auth_identity_not_found_error_message')));
}

6-11-2- findUserById

تابع مذکور با گرفتن یک متغیر و جایگذاری آن به عنوان نام کاربری کاربر و یا ایمیل او، کاربر مورد نظر را در صورت یافتن برمی‌گرداند. تابع فوق با گرفتن سه پارامتر ورودی $id، $cacheLifeTime و یک آرایه Tag، کاربر را در فهرست ذخیره موقت خود جستجو می‌کند و همچنین در صورت خالی بودن، آن را به حافظه موقت خود اضافه می‌کند.

نکته: دو پارامتر آخر اختیاری است.

مثال:

$user = BOL_UserService::getInstance()->findUserById($params['userId']);

6-11-3- getDisplayName

یک ورودی (شناسه کاربر) گرفته و بر اساس آن نام قابل نمایش کاربر را بر‌می‌گرداند.

مثال:

$userName = BOL_UserService::getInstance()->getDisplayName($userId);

6-11-4- getDisplayNamesForList

یک آرایه ورودی (شناسه کاربران) گرفته و بر اساس آن، یک آرایه لیست از نام قابل نمایش کاربران را بر‌می‌گرداند.

مثال:

$displayNameList = BOL_UserService::getInstance()->getDisplayNamesForList($authorIdList);

6-11-5- getUserName

یک ورودی (شناسه کاربر) گرفته و بر اساس آن نام کاربری کاربر را بر‌می‌گرداند.

مثال:

$this->assign('username', BOL_UserService::getInstance()->getUsername($userId));

6-11-6- getUserNamesForList

یک آرایه ورودی (شناسه کاربران) گرفته و بر اساس آن یک آرایه لیست از نام کاربران را بر‌می‌گرداند. به عنوان مثال:

$userNameList = $userService->getUserNamesForList($userIdList);

6-11-7- getUserUrl

شناسه کاربر را به عنوان ورودی گرفته و بر اساس آن آدرس مربوط به پروفایل کاربر را بر‌می‌گرداند.

مثال:

$userUrl = BOL_UserService::getInstance()->getUserUrl($userId);

6-11-8- getUserUrlForUsername

یک ورودی (نام کاربری) گرفته و بر اساس آن آدرس مربوط به پروفایل کاربر را بر‌می‌گرداند.

مثال:

$userUrl = BOL_UserService::getInstance()->getUserUrlForUsername($userDto-> username);

6-11-9- getUserUrlForUsername

نام کاربری را گرفته و بر اساس آن آدرس پروفایل کاربر مورد نظر را جستجو و برمی‌گرداند.

مثال:

$user = BOL_UserService::getInstance()->findByUsername($passwordValidationByToken-> username);

6-11-10- getUserUrlsListForUsernames

آرایه‌ای از نام‌های کاربری را گرفته و بر اساس آن آرایه‌ای از آدرس‌های کاربران مورد نظر را جستجو و برمی‌گرداند.

مثال:

$urlArr = BOL_UserService::getInstance()-> getUserUrlsListForUsernames($usernameList);

6-11-11- findByUserName

نام کاربری را گرفته و بر اساس آن کاربر مورد نظر را جستجو و برمی‌گرداند.

مثال:

$user = BOL_UserService::getInstance()->findByUsername($username);

6-11-12- findByEmail

ایمیل کاربری را گرفته و بر اساس آن کاربر مورد نظر را جستجو کرده و برمی‌گرداند.

مثال:

$parentUser = BOL_UserService::getInstance()->findByEmail($parentEmail);

6-11-13- saveLoginCookie

با استفاده از این تابع کوکی مورد نیاز برای ثبت ورود کاربر ساخته و ذخیره می‌شود.

مثال:

$loginCookie = $this->saveLoginCookie(OW::getUser()->getId());

6-11-14- getResetForm

با استفاده از این تابع فرم مربوط به فراموش کردن رمز عبور ساخته می‌شود.

مثال:

$form = $this->userService->getResetForm();
$this->addForm($form);

6-11-15- processResetForm

با استفاده از این تابع در صورتی که کاربر فرایند فراموشی رمز عبور را آغاز کرده باشد، رمز جدید ساخته شده و برای کاربر ارسال می‌شود.

مثال:

if ( $form->isValid($_POST) )
{
    $data = $form->getValues();
 
    try
    {
        $this->userService->processResetForm($data);
    }
    catch ( LogicException $e )
    {
        OW::getFeedback()->error($e->getMessage());
        $this->redirect();
    }
 
    OW::getFeedback()->info($language->text('base', 'forgot_password_success_message'));
    $this->redirect();
}

6-11-16- getDataForUsersList

با استفاده از این تابع کلیه اطلاعات مربوط به کاربرانی که آنلاین هستند و یا آخرین کاربران آنلاین و یا کاربرانی که هنوز حساب کاربری خود را فعال نکرده‌اند و غیره را بر اساس پارامتر ورودی $lisKey می‌توان دریافت نمود. این تابع سه پارامتر ورودی گرفته که اولین پارامتر آن ($listKey) نوع کاربر ‌(کاربرانی) که باید جستجو شوند ‌(غیرفعال، آنلاین و غیره) را مشخص می‌کند. دومین پارامتر $firstو سومین پارامتر $count به ترتیب مشخص می‌کنند از چندمین و چه تعداد کاربر مورد نظر است (برای مثال از سومین کاربر تا نهمین برابر است با $first=3 و $count=7).

مثال:

$service = BOL_UserService::getInstance();
return $service->getDataForUsersList($listKey, $first, $count);

6-11-17- findRecentlyActiveList

با استفاده از این تابع اطلاعات آخرین کاربران فعال گرفته می‌شود. این تابع سه پارامتر ورودی دارد: اولین پارامتر $first و دومین پارامتر $count مشخص می‌کنند از چندمین و چه تعداد کاربر مورد نظر است (برای مثال از سومین کاربر تا نهمین برابر است با $first=3 و $count=7) و سومین پارامتر $isAdmin که به صورت پیش‌فرض برابر false است مشخص می‌کند که آیا مدیریت سامانه نیز در نظر گرفته شود یا خیر.

مثال:

$userDtos = BOL_UserService::getInstance()->findRecentlyActiveList(0, 100);

6-11-18- findOnlineList

با استفاده از این تابع اطلاعات کاربران فعال گرفته می‌شود. این تابع دو پارامتر ورودی دارد: پارامتر اول ($first) و پارامتر دوم ($count) به ترتیب مشخص می‌کنند که از چندمین و چه تعداد کاربر مدنظر هستند. برای مثال از سومین کاربر تا نهمین برابر است با $first=3 و $count=7.

مثال:

$userDtos = BOL_UserService::getInstance()->findOnlineList(0, 100);

6-11-19- findUserIdByAuthToken

با استفاده از این تابع بر اساس توکن ساخته‌شده برای کاربر،‌ شناسه کاربر مربوطه بازیابی می‌شود. عموما در موارد خاصی توکن برای کاربر ساخته می‌شود، مثلا هنگامی که کاربر در سامانه ثبت‌نام کرده باشد. در این صورت برای او یک توکن جهت فعال‌سازی حساب کاربری ساخته می‌شود.

مثال:

if ( $token !== null )
{
    $this->userId = (int) BOL_UserService::getInstance()-> findUserIdByAuthToken($token);
}

6-11-20- addTokenForUser

با استفاده از این تابع برای کاربر با شناسه ورودی تابع مذکور توکن جدید ساخته شده و در صورتی که قبلا توکنی برای کاربر وجود داشته باشد توکن قبلی پاک شده و توکن جدید جایگزین آن می‌شود.

مثال‌:

$this->userId = $userId;
$this->token = BOL_UserService::getInstance()->addTokenForUser($this->userId);

6-11-21- getUserViewQuestions

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

مثال‌:

$questions = BOL_UserService::getInstance()->getUserViewQuestions($userId, $adminMode, $questionNames, $sectionNames);

6-11-22- getQueryFilter

با استفاده از این تابع می‌توان پالایش‌هایی برای دریافت کاربران سامانه وارد کرده و اطلاعات کاربران مورد نظر را دریافت نمود. این تابع دارای سه پارامتر ورودی است که اولین پارامتر ورودی آن آرایه‌ای از جداول مورد نظر برای اجرای پرسمان، دومین پارامتر آرایه‌ای از فیلدهای مورد نظر و سومین، آرایه‌ای از پارامترهای مورد نظر برای بررسی است.

مثال‌: تابع یافتن کاربران مسدود شده به شرح زیر است:

public function findBlockedUserList($userId, $first, $count)
{
    $queryParts = BOL_UserService::getInstance()->getQueryFilter(array(
        BASE_CLASS_QueryBuilderEvent::TABLE_USER => 'u'
    ), array(
        BASE_CLASS_QueryBuilderEvent::FIELD_USER_ID => 'blockedUserId'
    ), array(
        BASE_CLASS_QueryBuilderEvent::OPTION_METHOD => __METHOD__
    ));
 
    $query = "SELECT u.* FROM " . $this->getTableName() . " u " . $queryParts["join"]
        . " WHERE " . $queryParts["where"] . " AND u.userId=:userId  LIMIT :lf, :lc";
 
    return $this->dbo->queryForObjectList($query, $this->getDtoClassName(), array(
        "userId" => $userId,
        "lf" => $first,
        "lc" => $count
    ));
}

6-12- OW_User

از این کلاس برای دسترسی به برخی توابع مرتبط با جدول کاربران استفاده می‌شود در ذیل به مهم‌ترین آن‌ها اشاره شده است:

6-12-1- isAuthorized

تابع فوق سه پارامتر ورودی دارد که اولین آن ($groupname) نام گروه یا افزونه‌ای است که کاربر در حال حاضر وارد آن شده و یا با آن کار می‌کند، پارامتر دوم ($actionName) نام فعالیتی است که انجام می‌شود و پارامتر سوم آن ($extra) پارامتر اضافی در صورت نیاز است. با استفاده از تابع مذکور بررسی می‌شود که آیا کاربر در گروه مورد نظر اجازه فعالیت داده شده را دارد یا خیر.

مثال:

if ( !OW::getUser()->isAdmin() && !OW::getUser()->isAuthorized('iisnews', 'view') )
{
    $status = BOL_AuthorizationService::getInstance()->getActionStatus('iisnews', 'view');
    throw new AuthorizationException($status['msg']);
 
    return;
}

6-12-2- isAdmin

بررسی می‌کند که کاربر کنونی مدیر سامانه است یا خیر.

مثال:

if ( !OW::getUser()->isAdmin() )
{
    throw new AuthenticationException();
    exit();
}

6-12-3- isAuthenticated

بررسی می‌کند که هویت کاربر کنونی احراز شده است یا خیر.

مثال:

if ( !OW::getUser()->isAuthenticated() )
{
  $this->echoOut($_POST['feedAutoId'], array("error" => "You need to sign in to post."));
}

6-13- OW_Request

از این کلاس برای مدیریت درخواست‌های ارسالی مانند پارامترهای ارسالی از URL، آدرس IP درخواست‌دهنده و غیره استفاده می‌شود.

6-13-1- getRequestUri

این تابع درخواست URI مورد نظر را بر می‌گرداند. به عنوان مثال کد زیر بررسی می‌کند که آیا آدرس مورد درخواست کاربر آدرس «خروج از حساب کاربری» است یا خیر.

if (OW::getRequest()->getRequestUri() == 'sign-out'){
    return true;
}

6-13-2- isAjax

بررسی می‌کند آیا نوع درخواست به صورت Ajax است یا خیر.

مثال:

if ( !OW::getRequest()->isAjax() )
{
    throw new Redirect404Exception();
}

6-13-3- isPost

بررسی می‌کند آیا نوع درخواست Post است یا خیر. عموما از این تابع برای بررسی اینکه آیا فرم بعد از پر شدن اطلاعات ارسال شده یا خیر استفاده می‌شود.

مثال:

if (OW::getRequest()->isPost()) {
    if ($form->isValid($_POST)) {
        $data = $form->getValues();
            IISCONTACTUS_BOL_Service::getInstance()->addDepartment($data['email'], $data['label']);
            $this->redirect();
    }
}

6-14- OW_Session

از این کلاس برای مدیریت نشست ایجادشده برای کاربر استفاده می‌شود. در ادامه به مهم‌ترین توابع مربوط به این کلاس اشاره شده است:

6-14-1- set

این تابع دو پارامتر ورودی گرفته که اولین پارامتر ورودی ($key) کلید و پارامتر دوم ($value) مقدار مورد نظر برای کلید مذکور بوده و آن را در نشست مربوطه ذخیره می‌کند.

مثال:

6-14-1- set

این تابع دو پارامتر ورودی گرفته که اولین پارامتر ورودی ($key) کلید و پارامتر دوم ($value) مقدار مورد نظر برای کلید مذکور بوده و آن را در نشست مربوطه ذخیره می‌کند.

مثال:

OW::getSession()->set('iiscontactus.dept', $contactEmails[$data['to']]['label']);

6-14-2- get

این تابع کلید یک نشست را گرفته و مقدار آن را به عنوان خروجی برمی‌گرداند.

مثال:

$uidValue = OW::getSession()->get('mailbox.new_message_form_attachments_uid');

6-14-3- isKeySet

این تابع نام پارامتر ($key) را به عنوان ورودی گرفته و با استفاده از آن بررسی می‌کند که آیا پارامتری با نام داده شده در نشست مقداردهی شده است یا خیر

مثال:

if( OW::getSession()->isKeySet('privacyRedirectExceptionMessage') )
{
    $this->assign('message', OW::getSession()->get('privacyRedirectExceptionMessage'));
}

6-15- OW_Validator

یک کلاس پایه ‌(به همراه توابع اولیه) برای تعریف کلاس‌هایی برای اعتبارسنجی داده‌های واردشده در فیلد‌های ورودی فرم‌های سامانه است. برای مثال افزونه آلبوم تصاویر از یک کلاس اعتبارسنجی داده‌ها با نام AlbumPhotosValidator استفاده می‌کند که این کلاس از کلاس مذکور ارث می‌برد. سپس در هنگام تعریف فرم واردسازی آلبوم تصاویر این کلاس به فرم اضافه می‌شود.

$this->albumPhotosValidator = new AlbumPhotosValidator();
$photos->addValidator($this->albumPhotosValidator);

6-15-1- isValid

درون این تابع کلیه شرایط مربوط به بررسی صحت اطلاعات مورد نظر بررسی می‌شود.

مثال:

public function isValid( $data )
{
    $this->albumPhotosValidator->setAlbumId($data['from-album']);
 
    if ( !empty($data['to-album']) )
    {
        $this->getElement('to-album')->setRequired()->addValidator(new PHOTO_CLASS_AlbumOwnerValidator());
    }
 
    return parent::isValid($data);
}

6-15-2- getError

پیغام خطای مورد نظر با استفاده از این تابع گرفته می‌شود.

public function getJsValidator()
{
    return '{
        validate : function( value )
        {
            if ( value.length === 0 )
            {
                alert(OW.getLanguageText("photo", "no_photo_selected"));
                throw "Required";
            }
        }
    }';
}

6-15-3- setErrorMessage

متن پیغام خطای مورد نظر با استفاده از این تابع مقداردهی می‌شود.

مثال:

if ( !UTIL_Validator::isUserNameValid($value) )
{
    $this->setErrorMessage($language->text('base', 'join_error_username_not_valid'));
    return false;
}

6-15-4- getJsValidator

از این تابع برای بررسی صحت اطلاعات به صورت جاوااسکریپت استفاده می‌شود.

مثال:

function getJsValidator()
{
 
    return "{
       validate : function( value ){
            if( $('#address1').attr('checked') &&  !value ){ throw " . json_encode($this->getError()) . "; }
            return true;
    },
       getErrorMessage : function(){ return " . json_encode($this->getError()) . " }
    }";
}

نکته: کلاس‌های پایه‌ای دیگری نیز وجود دارند که از کلاس مذکور ارث برده و به عنوان کلاس‌های پایه برای استفاده تعریف شده‌اند؛ مانند کلاس RequiredValidator که عموما توابع getJsValidator و همچنین isValid آن از پیش تعریف شده است.

مثال زیر از این کلاس برای اجباری بودن پر شدن یک فیلد ورودی استفاده می‌کند:

$textarea->addAttribute('placeholder', $language->text('mailbox', 'message_invitation'));
$requiredValidator = new WyswygRequiredValidator();
$requiredValidator->setErrorMessage( $language->text('mailbox', 'chat_message_empty') );
$textarea->addValidator($requiredValidator);

کلاس‌های دیگری نیز مانند stringValidator، regularExpValidator و غیره وجود دارند که مانند کلاس بالا دارای توابع getJsValidator و همچنین isValid از پیش تعریف شده هستند.

6-16- OW_Cron

این کلاس به عنوان یک کلاس پایه‌ به جهت تعریف کلاس‌هایی برای بخش‌های مختلف که یک سری وظایف برای انجام به صورت دوره‌ای و در بازه‌های زمانی مختلف دارند استفاده می‌شود. از جمله وظایف دوره‌ای می‌توان به بررسی جدول ایمیل‌های آماده ارسال در هر 10 دقیقه و ارسال آن‌ها و یا بروز رسانی حافظه موقت در هر یک دقیقه و غیره اشاره نمود. شایان ذکر است که منظور از وظایف همان توابع تعریف شده است.

6-16-1- addJob

از این تابع برای اضافه کردن وظیفه‌‌ (وظایف) استفاده می‌شود که دارای دو پارامتر ورودی است: اولین پارامتر ($methodName) نام تابع مورد نظر و دومین پارامتر ورودی ($runInterval) نیز بازه زمانی بر حسب دقیقه است که تابع مورد نظر اجرا می‌شود. به صورت پیش‌فرض و در صورت عدم مقدار‌دهی 1 در نظر گرفته می‌شود.

6-16-2- getJobList

این تابع فهرستی از وظایف مربوطه برای اجرا را برمی‌گرداند.

در ادامه مثالی از چگونگی استفاده از زیرساخت کرون‌جاب برای افزونه «تصاویر» آمده است:

در اغلب موارد در تابع سازنده وظایف (توابع) تعریف‌شده مربوطه به زیرساخت کرون افزوده می‌شوند:

    parent::__construct();
 
    $this->addJob('albumsDeleteProcess');
    $this->addJob('contentIndexing');
    $this->addJob('cleareCache', 10);
    $this->addJob('deleteLimitedPhotos', 180);
    $this->addJob('updatePhotoTags');
}

در افزونه «تصاویر» تابع clearCache به صورت زیر و با هدف حذف داده‌های تصاویر موجود در حافظه‌نهان تعریف شده است.‌

public function cleareCache()
{
    PHOTO_BOL_PhotoCacheDao::getInstance()->cleareCache();
}

شایان ذکر است که فرزندان OW_Cron همواره دارای یک تابع run هستند:

public function run()
{
 
}

نام فایل حاوی کلاس فرزند OW_Cron می‌بایست cron.php باشد. فایل run.php واقع در شاخه ow_cron تمامی افزونه‌ها را بررسی کرده و در صورتی که دارای فایل cron.php باشند آن را اجرا می‌کند.

بخشی از کد مذکور که به دنبال فایل‌های cron.php موجود در افزونه‌ها می‌گردد، در زیر قابل مشاهده است.

foreach ( $plugins as $plugin )
{
    /* @var $plugin BOL_Plugin */
    $pluginRootDir = OW::getPluginManager()->getPlugin($plugin->getKey())->getRootDir();
    if ( file_exists($pluginRootDir . 'cron.php') )
    {
        include $pluginRootDir . 'cron.php';
        $className = strtoupper($plugin->getKey()) . '_Cron';
        $cron = new $className;

معرفی_کلاس_ها_و_توابع_مهم_در_موتوشاب.txt · آخرین ویرایش: 2019/01/15 12:45