model ها در فریمورک Yii

model ها، اشیایی هستند که منطق کسب و کار (business logic) و قوانین را نشان می دهند. برای ایجاد یک model، شما باید کلاس yii\base\Model یا زیرکلاس های آن را گسترش دهید.

ویژگی ها (Attributes)

Attribute ها یا ویژگی ها نشان دهنده ی داده های کسب و کار (business data) هستند. آنها می توانند مانند عناصر آرایه یا خواص (property) شیء قابل دسترسی باشند. هر attribute یک ویژگیِ قابل دسترسی عمومی از یک model می باشد. برای اینکه مشخص کنید، یک model چه attribute هایی دارد، شما باید متد yii\base\Model::attributes() را بازنویسی یا override کنید.

اجازه دهید نگاهی به مدل ContactForm از قالب اصلی برنامه (basic application template) بیندازیم.

<?php

   namespace app\models;

   use Yii;

   use yii\base\Model;

   /**

   * ContactForm is the model behind the contact form.

   */

   class ContactForm extends Model {

      public $name;

      public $email;

      public $subject;

      public $body;

      public $verifyCode;

      /**

      * @return array the validation rules.

      */

      public function rules() {

         return [

            // name, email, subject and body are required

            [['name', 'email', 'subject', 'body'], 'required'],

            // email has to be a valid email address

            ['email', 'email'],

            // verifyCode needs to be entered correctly

            ['verifyCode', 'captcha'],

         ];

      }

      /**

      * @return array customized attribute labels

      */

      public function attributeLabels() {

         return [

            'verifyCode' => 'Verification Code',

         ];

      }

      /**

      * Sends an email to the specified email address using the information

         collected by this model.

      * @param  string  $email the target email address

      * @return boolean whether the model passes validation

      */

      public function contact($email) {

         if ($this->validate()) {

            Yii::$app->mailer->compose()

               ->setTo($email)

               ->setFrom([$this->email => $this->name])

               ->setSubject($this->subject)

               ->setTextBody($this->body)

               ->send();

            return true;

         }

         return false;

      }

   }

?>

مرحله 1 - یک تابع به نام actionShowContactModel در SiteController با کد زیر ایجاد کنید.

public function actionShowContactModel() { 
   $mContactForm = new \app\models\ContactForm(); 
   $mContactForm->name = "contactForm"; 
   $mContactForm->email = "user@gmail.com"; 
   $mContactForm->subject = "subject"; 
   $mContactForm->body = "body"; 
   var_dump($mContactForm); 
}

ما در کد بالا، مدل ContactForm را تعریف کردیم، attribute ها را مقداردهی کردیم و مدل را بر روی صفحه ، نشان دادیم.

مرحله 2 - حال اگر در نوار آدرس مرورگر تان آدرس http://localhost:8080/index.php?r=site/show-contact-model را وارد کنید، آنچه را که مشاهده خواهید کرد، مطابق با تصویر زیر خواهد بود.

اگر مدل شما از yii\base\Model گسترش یابد، تمام متغیرهای عضو آن (عمومی و غیر استاتیک)، attribute های مدل شما خواهند بود. پنج attribute در مدل ContactForm وجود دارد: model − name, email, subject, body, verifyCode و شما می توانید به راحتی مواردبیشتری را اضافه کنید.

برچسبهای صفات (Attribute Labels)

شما اغلب نیاز به نمایش برچسب هایی دارید که در ارتباط با attribute ها هستند. به طور پیش فرض، برچسبهای attribute ها به صورت خودکار توسط متد yii\base\Model::generateAttributeLabel() تولید می شوند. برای مقداردهی برچسب های attribute به صورت دستی، شما می توانید متد yii\base\Model::attributeLabels() را بازنویسی یا override کنید.

مرحله 1 - اگر شما در مرورگرتان آدرس http://localhost:8080/index.php?r=site/contact را وارد کنید، صفحه زیر را مشاهده خواهید کرد :

توجه داشته باشید که برچسب attribute ها، همان نام آنها هستند.

مرحله 2 - اکنون تابع attributeLabels در مدل ContactForm را به شیوه زیر تغییر دهید.

public function attributeLabels() {
   return [
      'name' => 'name overridden',
      'email' => 'email overridden',
      'subject' => 'subject overridden',
      'body' => 'body overridden',
      'verifyCode' => 'verifyCode overridden',
   ];
}

مرحله 3 - اگر http://localhost:8080/index.php?r=site/contact را باز کنید، متوجه خواهید شد که برچسب ها همانطور که در تصویر زیر نشان داده شده است، تغییر کرده اند.

سناریوها

شما می توانید از یک model در سناریوهای مختلف استفاده کنید. به عنوان مثال، زمانی که یک کاربر مهمان در سایت می خواهد یک فرم "تماس با ما" ارسال کند، ما به تمام attribute های model نیاز داریم. هنگامی که یک کاربر عضو سایت، می خواهد همان کار را انجام دهد، او قبلا وارد سیستم شده است، بنابراین ما نام او را نمی خواهیم، زیرا ما می توانیم آن را از DB یا دیتابیس بخوانیم.

برای اعلام سناریوها، باید تابع scenarios() را بازنویسی یا override کنیم. این یک آرایه برمی گرداند بطوریکه کلیدهایش(key)، نام سناریو هستند و مقادیرش (value) ، صفات فعال (active attributes) هستند. "صفاتِ فعال" برای معتبر کردن سناریو می باشند.می توان به model ها به تعداد فراوان، "صفات فعال" اختصاص داد.

مرحله 1 - مدل ContactForm را به شیوه زیر تغییر دهید.

<?php
   namespace app\models;
   use Yii;
   use yii\base\Model;
   /**
   * ContactForm is the model behind the contact form.
   */
   class ContactForm extends Model {
      public $name;
      public $email;
      public $subject;
      public $body;
      public $verifyCode;
      const SCENARIO_EMAIL_FROM_GUEST = 'EMAIL_FROM_GUEST';
      const SCENARIO_EMAIL_FROM_USER = 'EMAIL_FROM_USER';
      public function scenarios() {
         return [
            self::SCENARIO_EMAIL_FROM_GUEST => ['name', 'email', 'subject', 
               'body', 'verifyCode'],
            self::SCENARIO_EMAIL_FROM_USER => ['email' ,'subject', 'body', 
               'verifyCode'],
         ];
      }
      /**
      * @return array the validation rules.
      */
      public function rules() {
         return [
            // name, email, subject and body are required
            [['name', 'email', 'subject', 'body'], 'required'],
            // email has to be a valid email address
            ['email', 'email'],
            // verifyCode needs to be entered correctly
            ['verifyCode', 'captcha'],
         ];
      }
      /**
      * @return array customized attribute labels
      */
      public function attributeLabels() {
         return [
            'name' => 'name overridden',
            'email' => 'email overridden',
            'subject' => 'subject overridden',
            'body' => 'body overridden',
            'verifyCode' => 'verifyCode overridden',
         ];
      }
      /**
      * Sends an email to the specified email address using the information 
         collected by this model.
      * @param  string  $email the target email address
      * @return boolean whether the model passes validation
      */
      public function contact($email) {
         if ($this -> validate()) {
            Yii::$app->mailer->compose()
               ->setTo($email)
               ->setFrom([$this->email => $this->name]) 
               ->setSubject($this->subject) 
               ->setTextBody($this->body)
               ->send();
            return true;
         }
         return false;
      }
   }
?>

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

مرحله 2 – هم اکنون قصد داریم، تابع actionContact را از SiteController تغییر دهیم.

public function actionContact() {
   $model = new ContactForm();
   $model->scenario = ContactForm::SCENARIO_EMAIL_FROM_GUEST;
   if ($model->load(Yii::$app->request->post()) && $model->
      contact(Yii::$app->params ['adminEmail'])) {
         Yii::$app->session->setFlash('contactFormSubmitted');  
         return $this->refresh();
   }
   return $this->render('contact', [
      'model' => $model,
   ]);
}

مرحله 3 – آدرس http://localhost:8080/index.php?r=site/contact را در مرورگرتان تایپ کنید. همانطور که در تصویر می بینید، مقدار دهی تمام attribute های مدل ضروری هستند.

مرحله 4 - اگر سناریو مدل را در actionContact تغییر دهید، همانطور که در کد زیر نشان داده شده است، می بینید که attribute نام، دیگر مورد نیاز نیست.

$model->scenario = ContactForm::SCENARIO_EMAIL_FROM_USER;

مقداردهی انبوه (Massive Assignment)

انتساب یا مقداردهی انبوه، یک راه مناسب برای ایجاد یک model با  attribute های مختلفِ ورودی، از طریق یک خط کد است.

خطوط کد -

$mContactForm = new \app\models\ContactForm; 
$mContactForm->attributes = \Yii::$app->request->post('ContactForm');

کدهای بالا مطابق است با -

$mContactForm = new \app\models\ContactForm; 
$postData = \Yii::$app->request->post('ContactForm', []); 
$mContactForm->name = isset($postData['name']) ? $postData['name'] : null; 
$mContactForm->email = isset($postData['email']) ? $postData['email'] : null; 
$mContactForm->subject = isset($postData['subject']) ? $postData['subject'] : null; 
$mContactForm->body = isset($postData['body']) ? $postData['body'] : null;

کد قبلی ساده تر است. توجه داشته باشید که مقداردهی انبوه (massive assignment) فقط به attribute های امن اعمال می شود. آنها attribute های سناریو جاری هستند که در تابع scenario() لیست شده اند.

خروجی گرفتن از داده ها

اغلب در model ها نیاز به خروجی گرفتن داده ها در فرمت های مختلف داریم. برای تبدیل مدل به یک آرایه، باید تابع actionShowContactModel را در SiteController تغییر دهیم -

public function actionShowContactModel() {
   $mContactForm = new \app\models\ContactForm();
   $mContactForm->name = "contactForm";
   $mContactForm->email = "user@gmail.com";
   $mContactForm->subject = "subject";
   $mContactForm->body = "body";
   var_dump($mContactForm->attributes);
} 

در نوار آدرس مرورگرتان آدرس http://localhost:8080/index.php?r=site/show-contact-model را وارد کنید و نتیجه زیر را مشاهده خواهید کرد -

برای تبدیل model به فرمت JSON، تابع actionShowContactModel را به شیوه زیر تغییر دهید -

public function actionShowContactModel() {
   $mContactForm = new \app\models\ContactForm();
   $mContactForm->name = "contactForm";
   $mContactForm->email = "user@gmail.com";
   $mContactForm->subject = "subject";
   $mContactForm->body = "body";
   return \yii\helpers\Json::encode($mContactForm);
}

آنچه در مرورگر به عنوان خروجی کد بالا مشاهده می کنید به شکل زیر می باشد -

{
   "name":"contactForm",
   "email":"user@gmail.com",
   "subject":"subject",
   "body":"body ",
   "verifyCode":null
}

نکات مهم

model ها در برنامه هایی با طراحی خوب، بسیار سریعتر از controller ها هستند.

model ها باید -

• شامل  business logic باشند.
• شامل قوانین اعتبارسنجی (validation rules) باشند.
• شامل صفات یا attribute هایی باشند.
• کدهای HTML در آنها نباشد.
• مستقیما به request ها یا درخواست ها دسترسی نداشته باشند.
• از سناریوهای زیادی تشکیل نشده باشند.