يعد روبي أون ريلز Ruby on Rails -أو اختصارًا ريلز Rails- من أشهر أطر العمل بلغة روبي Ruby المستخدمة في تطوير المواقع وتطبيقات الويب بسهولة وسرعة، إذ يمكن تثبيت إطار العمل باستخدام أداة سطر الأوامر rbenv، التي تتيح إمكانية إنشاء بيئة لتطوير التطبيقات باستخدام روبي أون ريلز والتبديل بين نسخ روبي المختلفة، كما تمكّنك من تخصيص وتحديد نسخة روبي مختلفة لكل تطبيق تطوره على حدى بغض النظر عن النسخة الافتراضية العامة ضمن النظام، كما تمكّنك من تحديد نسخة روبي محددة لكل مستخدم على حدى مع ترك إمكانية تغيير تلك النسخة باستخدام متغيرات البيئة.

سنتعرف في هذا المقال على طريقة تثبيت روبي أون ريلز باستخدام rbenv و gem، إذ سنبدأ بتثبيت الحزم المطلوبة لعمل rbenv ثم روبي وبعدها سنثبت الإضافة ruby-build لنتمكن من تثبيت أحد إصدارات روبي المتوفرة. بعد ذلك، سنستخدم gem لتثبيت إطار ريلز لنتمكن من استخدام روبي ضمنه من أجل تطوير تطبيقات الويب، وسنتعلم أيضًا طريقة التحقق من توفر التحديثات لنسخة rbenv المثبتة، وطريقة إزالة تثبيت نسخ روبي وأيضًا rbenv.

ستحتاج لتطبيق الخطوات في هذا المقال إلى ما يلي:

• نظام خادم أوبنتو 22.04 مثبت مع إمكانية الوصول لحساب مستخدم يمكنه تنفيذ الأمر sudo وجدار ناري مثبت.
• نسخة نود Node.js مثبتة على النظام، إذ تحتاج بعض مزايا ريلز، مثل ميزة أنبوب الموارد Asset Pipeline لبيئة تشغيل جافا سكريبت لعملها.

تثبيت أداة rbenv واعتماديتها

تعتمد لغة روبي على عدد من الحزم التي يمكنك تثبيتها من خلال مدير الحزم، وحالما تثبّت هذه الحزم، يمكنك تثبيت rbenv واستخدامها لتثبيت روبي.

نبدأ بتنفيذ أمر تحديث قائمة الحزم على النظام:

$ sudo apt update

ثم نثبّت الاعتماديات المطلوبة تثبيت روبي:

$ sudo apt install git curl libssl-dev libreadline-dev zlib1g-dev autoconf bison build-essential libyaml-dev libreadline-dev libncurses5-dev libffi-dev libgdbm-dev

بعد ذلك، يمكننا تثبيت rbenv باستخدام الأمر curl لتنزيل النص البرمجي المستخدم لتثبيته الموجود على غيت هب GitHub وتمريره مباشرةً إلى الأمر bash لتنفيذه على النحو التالي:

$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash

نضيف المسار "rbenv/bin./~" إلى المتغير PATH$ لنتمكن من استخدام أداة سطر الأوامر rbenv، وذلك بتعديل الملف bashrc./~ ليُطبق التعديل ضمن جلسات الطرفية اللاحقة:

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc

ثم نضيف أمر تحميل rbenv إلى نفس الملف مجددًا على النحو التالي:

$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc

ولتطبيق تلك التعديلات على جلسة الطرفية الحالية ننفذ الأمر التالي:

$ source ~/.bashrc

نستخدم الأمر type لنتأكد من تطبيقها وتوفر الأمر rbenv، إذ سيعرض هذا الأمر معلومات حول rbenv على النحو التالي:

$ type rbenv

ليظهر لنا الخرج التالي:

rbenv is a function
rbenv ()
{
    local command;
    command="${1:-}";
    if [ "$#" -gt 0 ]; then
        shift;
    fi;
    case "$command" in
        rehash | shell)
            eval "$(rbenv "sh-$command" "$@")"
        ;;
        *)
            command rbenv "$command" "$@"
        ;;
    esac
}

وبذلك نكون ثبتنا كلًا من الأداتين rbenv و ruby-build، وسنبدأ في الفقرة التالية بتثبيت روبي.

تثبيت روبي باستخدام ruby-build

بعد أن ثبتنا الإضافة ruby-build، يمكننا تثبيت أي نسخة من روبي نحتاجها عبر سطر الأوامر ونبدأ بعرض النسخ المتاحة بتنفيذ الأمر التالي:

$ rbenv install -l

ليظهر لنا قائمة بالنسخ المتوفرة:

2.7.7
3.0.5
3.1.3
3.2.0
jruby-9.4.0.0
mruby-3.1.0
picoruby-3.0.0
truffleruby-22.3.1
truffleruby+graalvm-22.3.1

Only latest stable releases for each Ruby implementation are shown.
Use 'rbenv install --list-all / -L' to show all local versions.

لنختار نسخة روبي 3.2.0 ونثبتها كما يلي:

$ rbenv install 3.2.0

تستغرق عملية التنزيل والتثبيت بعض الوقت لإنهائها، وبعد ذلك يمكننا تعيين تلك النسخة على أنها نسخة افتراضية باستخدام الأمر الفرعي global على النحو التالي:

$ rbenv global 3.2.0

ونتحقق من ذلك بعرض نسخة روبي الحالية:

$ ruby -v

ليظهر لنا معلومات النسخة التي اخترناها سابقًا على النحو التالي:

$ ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-linux]

وبذلك نكون قد ثبتنا نسخة من نسخ روبي وعيناها على أنها نسخة عامة افتراضية وأصبحت جاهزة للعمل عليها. سنعد في الفقرة التالية مكتبة gems وإطار ريلز

التعامل مع المكتبات Gems

الطريقة التي تنشر بها مكتبات روبي تسمى gems ويمكن استخدام الأمر gem لإدارتها وأيضًا لتثبيت إطار ريلز، فعند تثبيت أي مكتبة منها ينشأ لها ملفات توثيق محلي، وقد تستغرق تلك العملية وقتًا لذا يمكننا إلغاؤها بإنشاء ملف إعدادات في المجلد "gemrc./~" وإضافة تعليمة ضمنه بتنفيذ الأمر التالي:

$ echo "gem: --no-document" > ~/.gemrc

ونبدأ بتثبيت أول أداة وهي Bundler، التي تفيد في إدارة الاعتماديات ضمن المشروع ويعتمد عليها إطار ريلز في عمله:

$ gem install bundler

ليظهر لنا الخرج التالي:

Fetching bundler-2.4.5.gem
Successfully installed bundler-2.4.5
1 gem installed

يمكننا استخدام الأمر gem env (الأمر الفرعي env هو اختصار للأمر environment)، لعرض معلومات عن البيئة والاعدادات الحالية للمكتبات gems، إذ يمكننا مثلًا عرض مسار تثبيت الاعتماديات على النظام بتنفيذ الأمر الفرعي home على النحو التالي:

$ gem env home

ليظهر لنا المسار على النحو التالي:

/home/hassan/.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0

بعد أن ثبتنا gems يمكننا الآن تثبيت إطار ريلز وهو ما سنشرحه في الفقرة التالية.

تثبيت ريلز

لتثبيت ريلز نُنفذ الأمر gem install مع الخيار v- لتحديد الإصدار المطلوب إذ سنستخدم في هذا المقال الإصدار 7.0.4:

$ gem install rails -v 7.0.4

يُثبت الأمر السابق المكتبة التي حددناها مع اعتمادياتها، وبما أن ريلز إطار عمل لتطوير تطبيقات الويب المعقدة لذا فهو يحتوي على العديد من الاعتماديات، وهو سبب استغراق تنفيذ الأمر السابق بعض الوقت وسينتج عنه رسالة تفيد بتثبيت ريلز بنجاح مع اعتمادياته:

...
Successfully installed rails-7.0.4
35 gems installed

يمكننا استعراض الإصدارات المتاحة لاختيار تثبيت إصدار مختلف من ريلز عن طريق البحث باستخدام الأمر search، الذي سيعرض قائمة بالإصدارات المتاحة للتنزيل، ويمكننا الاختيار منها وتثبيت أحد تلك الإصدارات، ففي الأمر التالي سنختار الإصدار 4.2.7:

$ gem search '^rails$' --all
$ gem install rails -v 4.2.7

وإذا أردنا تثبيت أحدث إصدار من ريلز يمكننا تنفيذ نفس الأمر لكن بدون تحديد رقم الإصدار:

$ gem install rails

إذ سيُنشئ rbenv مجلدًا لملفات shims، الذي يشير إلى الملفات المستخدمة من قبل إصدار روبي المُفعل حاليًا. يدير rbenv من خلال الأمر الفرعي rehash ملفات shims ضمن ذلك المجلد، وذلك لمطابقة كل أمر من أوامر روبي عبر كل إصدار مثبت من روبي على الجهاز الخاص بنا. عند تثبيت إصدار جديد من روبي أو مكتبة gem توفر أوامرًا يمكن تنفيذها مثل ريلز، يجب تنفيذ الأمر التالي:

$ rbenv rehash

للتحقق من تثبيت ريلز بنجاح يمكنك طباعة رقم إصداره باستخدام الأمر التالي:

$ rails -v

فإذا انتهى التثبيت بنجاح سيظهر لنا رقم إصدار ريلز المُثبت:

Rails 7.0.4

الآن، يمكننا البدء في اختبار وتثبيت روبي ضمن ريلز وتطوير تطبيقات الويب باستخدامه، وسنستعرض في الفقرة التالية طريقة تحديث rbenv لآخر نسخة متوفرة.

تحديث rbenv

بما أننا ثبتنا rbenv يدويًا باستخدام Git، يمكننا تحديثه لآخر إصدار باستخدام الأمر git pull ضمن المجلد rbenv./~ على النحو التالي:

$ cd ~/.rbenv
$ git pull

وبذلك نتأكد من استخدام أحدث إصدار متاح من rbenv.

إلغاء تثبيت إصدارات روبي

قد تتراكم الإصدارات الإضافية التي قد ننزلها من روبي ضمن المجلد "rbenv/versions./~"، ولحل تلك المشكلة يمكننا استخدام الأمر الفرعي uninstall الذي توفره الإضافة ruby-build لإزالة الإصدارات السابقة التي لا نحتاج لها، فمثلًا يمكن استخدام الأمر التالي لإلغاء تثبيت إصدار روبي بنسخة 3.2.0:

$ rbenv uninstall 3.2.0

يفيد استخدام أمر إلغاء تثبيت الذي يوفره rbenv بتنظيف ذلك المجلد وإزالة الإصدارات القديمة من روبي لنبقي فقط على ما نحتاج لاستخدامه حاليًا.

إلغاء تثبيت rbenv

يمكننا إزالة rbenv من نظام التشغيل في حال عدم الحاجة لاستخدامه، وذلك بفتح الملف "bashrc./~" ضمن أي محرر للنصوص مثل نانو nano على النحو التالي:

$ nano ~/.bashrc

ونبحث عن السطرين التاليين ونحذفهما من الملف:

...
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

بعد حذف هذين السطرين نحفظ الملف ونخرج من المحرر بالضغط على المفتاحين "CTRL + X" ثم "Y" و "Enter" لتأكيد حفظ الملف، ويمكننا بعدها إزالة rbenv وجميع إصدارات روبي المثبتة باستخدام الأمر التالي:

$  rm -rf `rbenv root`

ستطبق هذه التغييرات ضمن الجلسة بعد تسجيل الخروج وتسجيل الدخول مرة أخرى.

الخاتمة

تعلمنا في هذا المقال كيفية تثبيت rbenv والأمر gem لتثبيت إطار عمل روبي أون ريلز كاملًا، وبذلك يمكننا إنشاء مشاريع تطوير تطبيقات الويب الجديدة.

ترجمة -وبتصرف- للمقال How To Install Ruby on Rails with rbenv on Ubuntu 22.04 لأصحابه Brian Hogan و Lisa Tagliaferri و Jeanelle Horcasitas.

اقرأ أيضًا

• المقال السابق: تثبيت روبي وإعداد بيئة برمجة محلية في أوبنتو لينكس
• مدخل إلى إطار العمل Ruby on Rails
• كل ما تحتاج إليه لتعلم البرمجة بـ Ruby
• توثيق روبي أون ريلز العربي

ريلز أو Ruby on Rails هو أحد أكثر الإطارات المعروفة للمطورين الذين يتطلعون إلى إنشاء مواقع وتطبيقات ويب، التي تجمع بين لغة برمجة روبي مع إطار العمل ريلز framework Rails مما جعل إنشاء التطبيقات الويب أكثر بساطة.

لتثبيت ريلز يمكنك استخدام أداة سطر الأوامر rbenv التي ستوفر لك بيئة صلبة لتطوير تطبيقات ريلز تتيح لك التبديل بسهولة بين إصدارات Ruby و إبقاء فريقك بأكمله على نفس الاصدار. توفر لك rbenv دعما لتحديد اصدارات روبي الخاصة بالتطبيق وتغيرها لكل مستخدم، كما تسمح لك باستخدام متغير لإعادة تحديد إصدار روبي.

سوف يوضح لك هذا المقال عملية تثبيت ريلز باستخدام rbenv.

## المتطلبات الأساسية

من أجل متابعة هذا المقال تحتاج إلى:

• إعداد خادم اوبنتو 18.04 و تملك مستخدم غير جذري (non-root) يملك صلاحيات sudo و مثبت عليه جدار حماية. يمكنك اعداده بالعودة إلى مقال الإعداد الأولي لخام اوبنتو
• قم بثبيت Node.js باستخدام official PPA كما هو موضح في كيفية تثبيت Node.js على 18.04 اوبنتو إذ تعتمد بعض ميزات ريلز مثل خط أنابيب الأصول Asset Pipeline ومُشغل جافاسكربت الآني runtime JavaScript على ما يوفره Node.js.

الخطوة الأولى: تثبيت rbenv ومتطلباته

تعتمد Ruby على عدة حزم يمكنك تثبيتها من خلال apt-get وبمجرد تثبيتها يمكنك تثبيت rbenv واستخدامه لتثبيت روبي.

أولاً، قم بتحديث قائمة الحزمة الخاصة بك:

 $ sudo apt update 

من قم بتثبيت المتطلبات اللازمة لتشغيل روبي بتنفيذ الأمر التالي .

$ sudo apt install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev

بمجرد الانتهاء من تثبيت المتطلبات يمكنك البدء بتثبيت rbenv من GitHub ووضعه داخل المجلد rbenv ./~:

$ git clone https://github.com/rbenv/rbenv.git ~ / .rbenv 

بعد ذلك لابد من تعريف PATH$ الخاص بك على rbenv لاستخدامها في واجهة سطر الأوامر ويكون ذلك بإضافة الملف rbenv/bin./~ إلى PATH$ الخاص بك داخل الملف bashrc./~ ولكن تذكر من أجل ظهور التغيرات لابد من إنهاء ومن ثم إعادة تشغيل واجهة سطر الأوامر؛ انظر للأمر التالي:

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc 

الآن أضف الأمر "(-eval "$(rbenv init إلى الملف bashrc./~ من أجل أن يتم تجميل rbenv تلقائيا:

$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc

لتطبيق التغييرات التي أجرتها على الملف bashrc./~ على جلسة الصدفة shell الحالية نفذ الأمر التالي:

$ source ~/.bashrc

للتحقق من إعدادات rbenv أنه تم تثبيتها بشكل صحيح استخدم الأمر type الذي سيعرض المزيد من المعلومات حول rbenv:

$ type rbenv

سوف يعرض الأمر ما يلي:

rbenv is a function
rbenv ()
{
    local command;
    command="${1:-}";
    if [ "$#" -gt 0 ]; then
        shift;
    fi;
    case "$command" in
        rehash | shell)
            eval "$(rbenv "sh-$command" "$@")"
        ;;
        *)
            command rbenv "$command" "$@"
        ;;
    esac
}

بعد ذلك قم بتنزيل ruby-build وهو عبارة عن إضافة plugin، إذ تضيف الأمر rbenv install الذي يسهل عملية تنزيل الإصدارات الجديدة من روبي:

$ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

في هذه المرحلة تم تثبيت كل من rbenv و ruby-build لنبدأ الآن بتثبيت روبي:

الخطوة الثانية: تثبيت روبي مع ruby-build

بعد تثبيت ruby-build يمكنك الآن تثبيت إصدارات روبي التي تحتاج بأمر بسيط. اولا سنعرض جميع الإصدارت المتاحة من روبي:

$ rbenv install -l

ستظهر لك قائمة كبيرة من الإصدارات التي يمكن تثبيتها، لنقم بتثبيت الإصدار 2.5.1 المتوفر وقت كتاب هذا المقال:

$ rbenv install 2.5.1

من أجل تثبيت إصدار روبي الذي قمنا بتثبيته كإصدار الافتراضي استخدم الرمز global كجزء من الأمر:

$ rbenv global 2.5.1

للتحقق من أن التثبيت تم بشكل صحيح تحقق من رقم اصدار روبي:

$ ruby -v

إذا قمت بتثبيت نفس الاصدار السابق لابد ان تظهر لك المخرجات التالية:

ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux]

لتثبيت إصدار مختلف من روبي قم تنفيذ الأمر rbenv مع رقم إصدار مختلف مثل: rbenv install 2.3.0 ثم rbenv global 2.3.0.

الآن لديك إصدار واحد على الأقل من روبي قم بتثبيته و تعينه باصدار افتراضي لروبي فبعد ذلك سوف نبدأ بإعداد ريلز والجواهر gems الخاصة بها.

الخطوة الثالثة: العمل مع الجواهر Gems

الجواهر Gems هي الطريقة التي يتم بها توزيع مكتبات روبي، استخدام الأمر gem لإدارة هذه gems كما سوف نستخدم هذا الأمر لتثبيت ريلز.

أثناء تثبيت gem تعمل عملية التثبيت بإنشاء وثائق محلية مما يضيف وقت أطول أثناء عملية تثبيت كل gem، لذلك سنوقف هذه العملية عن طريق إنشاء ملف يسمى gemrc./~ الذي يحتوي على الاعدادت اللازمة لإيقاف هذه الميزة:

$ echo "gem: --no-document" > ~/.gemrc

المُحزِّم Bundler هي عبارة عن أداة يستخدمها gem لإدارة ما يعتمد عليه المشاريع، بالأمر التالي سنثبت Bundler الذي يعتمد عليه ريلز.

$ gem install bundler

ستظهر المخرجات التالية:

Fetching: bundler-1.16.2.gem (100%)
Successfully installed bundler-1.16.2
1 gem installed

يمكنك استخدام الأمر gem env (كلمة env بالأمر هي اختصار من كلمة environment) لمعرفة المزيد حول من البيئات والإعدادات ب gems، بإمكانك معرفة مكان تثبيت gems باستخدام متغير home انظر للمثال :

$ gem env home

سوف يعرض لك الناتج التالي:

/home/sammy/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0

بمجرد الإنتهاء من إعدادات gems يمكنك تثبيت ريلز بالخطة التالية:

الخطوة الرابعة: تثبيت ريلز

من أجل تثبيت ريلز استخدم الأمر gem install مع الراية ‎-v لتحديد الإصدار، في هذا المقال التعليمي، سنثبت الإصدار 5.2.0:

$ gem install rails -v 5.2.0

يقوم الأمر gem بتثبيت الجواهر المحددة وكذلك كل ما تعتمد عليه. تُعد ريلز لتطوير الويب معقدة إذ تعتمد على العديد التبعيات ، لذلك تستغرق عملية التثبيت بعض الوقت،و لكن بالنهاية سترى رسالة تفيد بأن ريلز مثبت، بالإضافة إلى كل ما تعتمد عليه:

Successfully installed rails-5.2.0
38 gems installed

ملاحظة: إذا كنت ترغب في تثبيت إصدار مختلف من ريلز، يمكنك عرض الإصدارات الصالحة من ريلز من خلال إجراء عملية بحث، مما يؤدي إلى لإظهار قائمة طويلة من الإصدارات، يمكننا بعد ذلك تثبيت إصدار معين، مثل 4.2.7:

$ gem search '^rails$' --all
$ gem install rails -v 4.2.7

في حال كنت ترغب في تثبيت أحدث إصدار من ريلز نفذ الأمر دون تحديد رقم الاصدار:

$ gem install rails

يعمل rbenv عن طريق إنشاء مجلد shims، والذي يشير إلى الملفات المستخدمة بإصدار ريلز المفعل حاليًا،من خلال الأمر الفرعي rehash يقوم rbenv بإصلاح shims في هذا المجد لربط كل أمر في روبي عبر كل إصدار مثبت من روبي على الخادم الخاص بك. كلما تم تثبيت إصدار جديد من روبي أو gem نفذ هذا الامر.

$ rbenv rehash

تحقق من تثبيت ريلز بشكل صحيح عن طريق طباعة اصداره باستخدام هذا الأمر:

$ rails -v

إذا تم تثبيته بشكل صحيح ، سترى إصدار ريلز الذي تم تثبيته:

Rails 5.2.0

في هذه المرحلة سنقوم بالبدء في اختبار تثبيت ريلز والبدء في تطوير تطبيقات الويب، حافظ على تحديث rbenv باستمرار.

الخطوة الخامسة: تحديث rbenv

نظرًا لأنك قمت بتثبيت rbenv يدويًا باستخدام Git، يمكنك تحديثه إلى الإصدار الأحدث في أي وقت باستخدام أمر git pull في المجلد rbenv./~:

$ cd ~/.rbenv
$ git pull

هكذا سنضمن أننا نستخدم أحدث إصدار من rbenv المتاحة.

الخطوة السادسة: إلغاء تثبيت إصدارات روبي

أثناء تنزيل إصدارات إضافية من روبي يمكنك تجميع إصدارات أكثر مما تريد في المجلد rbenv/versions./~ استخدم الأمر uninstall الموجود ب ruby-build لإزالة أي من الإصدارات السابقة على سبيل المثال إزالة الاصدار 2.1.3:

$ rbenv uninstall 2.1.3

باستخدام الأمر `rbenv uninstall` يمكنك من إزالة  الإصدارات القديمة من روبي بحيث لا يكون لديك تثبيت أكثر مما تستخدمه حاليًا.

الخطوة السابعة: إلغاء تثبيت rbenv

إذا قررت أنك لم تعد ترغب في استخدام rbenv، فيمكنك إزالته من نظامك ،من أجل القيام بذلك  افتح أولاً ملف `bashrc./~` في المحرر الخاص بك:

$ nano ~/.bashrc

ابحث عن السطرين التاليين من الملف ‎~/.bashrc ثم قم بحذفها:

export PATH="$HOME/.rbenv/bin:$PATH" eval "$(rbenv init -)"

احفظ الملف واخرج من المحرر،ثم قم بإزالة rbenv وجميع إصدارات روبي المثبتة بهذا الأمر:

rm -rf rbenv root

سجل الخروج وقم بالعودة لحفظ التغييرات على الصدفة shell الخاص بك.

الخلاصة

في هذا المقال التعليمي قمت بتثبيت rbenv وريلز ويمكن الآن الانتقال إلى توثيق ريلز على موسوعة حسوب لمزيد من المعلومات.

ترجمة -وبتصرف- للمقال How To Install Ruby on Rails with rbenv on Ubuntu 18.04 لصاحبيه Brian Hogan و Lisa Tagliaferri

تابعنا في الدرس السابق من هذه السلسلة مرجع الارتباط المفصّل وسنتابع في هذا الدرس الحديث عن مرجع ارتباط has_one.

4.2 مرجع ارتباط has_one

يُنشئ ارتباط has_one تطابق واحد لواحد (one-to-one) مع كائن آخر، بمصطلحات قاعدة البيانات، هذا الارتباط يعلن أن الصنف الآخر يحتوي على مفتاح خارجي، وإذا كان هذا الصنف يحتوي على مفتاح خارجي، فيجب عليك في هذه الحالة استخدام belongs_to بدلا من ذلك.

4.2.1 الأساليب المضافة بواسطة has_one

عند إعلان ارتباط has_one، فإن الفئة المُعلنة ستحصل على 5 أساليب متعلقة بالارتباط:

• association
• (association=(associate
• ({} = build_association(attributes
• ({} = create_association(attributes
• ({} = create_association!(attributes
• reload_association

في كل هذه الأساليب، يُستبدل الارتباط مع symbol المُمرر كمعامل أول إلى has_one، على سبيل المثال:

class Supplier < ApplicationRecord
  has_one :account
end

فإن كل مثيل من نموذج Supplier سيحصل على هذه الأساليب:

account
account=
build_account
create_account
create_account!
reload_account

Quote

ملاحظة:
يجب عليك عند إنشاء ارتباط has_one أو belongs_to جديد استخدام بادئة _build لبناء الارتباط، بدلا من أسلوب association.build الذي سيستخدم لارتباطات has_many أو has_and_belongs_to_many، ولإنشاء واحد استخدم بادئة _create .

4.2.1.1 association

يُرجع أسلوب association الكائن المرتبط إن وجد، وإلا، فسيرجع nil.

@account = @supplier.account

إذا أُسترد الكائن المرتبط بالفعل من قاعدة البيانات لهذا الكائن، ستٌسترجع النسخة المخبأة، ولتجاوز هذا السلوك(وإجبار قاعدة البيانات على القراءة)، استدعي #reload_association في الكائن الأب.

@account = @supplier.reload_account

4.2.1.2 (association=(associate

يُعيّن أسلوب =association كائن مرتبط إلى هذا الكائن، وفي ما وراء الكواليس، هذا يعني استخراج المفتاح الرئيسي من هذا الكائن وتعيين مفتاح الخارجي للكائن المرتبطة إلى نفس القيمة.

@supplier.account = @account

4.2.1.3 ({} = build_association(attributes

يرجع أسلوب build_association كائن جديد للنوع المرتبط، وهذا الكائن سيُنشئ من السمات المُمررة، وسيُعين الارتباط بمفتاحه الخارجي، لكن لن يُحفظ الكائن المرتبط.

@account = @supplier.build_account(terms: "Net 30")

4.2.1.4 ({} = create_association(attributes

يرجع أسلوب create_association كائن جديد من النوع المرتبط، وهذا الكائن سيُنشئ من السمات الممررة، وسيُعين الارتباط بمفتاحه الخارجي، وبمجرد النجاح في جميع التحقيقات (validations) المحددة في النموذج المرتبط، سيُحفظ الكائن المرتبط.

@account = @supplier.create_account(terms: "Net 30")

4.2.1.5 ({} = create_association!(attributes

يعمل كما create_association في الأعلى، لكنه يصدر ActiveRecord::RecordInvalid إذا كان السجل (record) غير صالح.

4-2-2 خيارات has_one

في حين يستخدم Rails الافتراضات الذكية والتي تعمل بشكل جيد في أغلب الأحيان، لكن في بعض الأوقات ستحتاج إلى تخصيص سلوك مرجع ارتباط has_one، ويمكن تحقيق هذه التخصيصات بسهولة عن طريق تمرير الخيارات عند إنشاء الارتباط، فعلى سبيل المثال، يستخدم هذا الارتباط اثنين من هذه الخيارات:

class Supplier < ApplicationRecord
  has_one :account, class_name: "Billing", dependent: :nullify
end

يدعم ارتباط has_one هذه الخيارات:

• as:
• autosave:
• class_name:
• dependent:
• foreign_key:
• inverse_of:
• primary_key:
• source:
• source_type:
• through:
• validate:

4.2.2.1 as:

يشير تعيين خيار as: على أن الارتباط متعدد الأشكال، وستجد المزيد من التفاصيل حول الارتباطات متعددة الأشكال بالتفاصيل في الأعلى.

4.2.2.2 autosave:

إذا عيّنت خيار autosave: إلى true، فإن Rails سيحفظ أي أعضاء محملين وسيدمر الأعضاء الذي وُضع عليهما علامة للتدمير كلما حفظت كائن الأب.

4.2.2.3 class_name:

إذا لم يكن بالإمكان اشتقاق اسم النموذج الآخر من اسم الارتباط، يمكنك استخدام خيار class_name: لتوفير اسم النموذج، فعلى سبيل المثال، إذا كان المُورّد يمتلك حساب، لكن اسم النموذج الحالي الذي يحتوي على الحسابات هو Billing، فيمكنك فعل التالي:

class Supplier < ApplicationRecord
  has_one :account, class_name: "Billing"
end

4.2.2.4 dependent:

يتحكم في ما يحدث للكائن المرتبط عند حذف مالكه:

• destroy: سيدمر كائن المرتبط أيضا.
• delete: سيحذف الكائن المرتبط مباشرة من قاعدة البيانات (ولن يعمل دوال الاستدعاء).
• nullify: سيُعين المفتاح الخارجي إلى NULL ولن يعمل دوال الاستدعاء.
• restrict_with_exception: سيصدر استثناء إذا كان هنالك كائن مرتبط.
• restrict_with_error: سيضاف خطأ إلى المالك إذا كان هنالك كائن مرتبط.

من الضروري عدم تعيين أو ترك خيار nullify: للارتباطات التي تملك قيود NOT NULL على قاعدة البيانات، إذا لم تعيّن dependent لتدمير هذه الارتباطات فلن تتمكن من تغيير كائن المرتبط لأنه سيُعيّن المفتاح الخارجي للكائن المرتبط الأولي إلى NULL التي هي غير مسموح بها.

4.2.2.5 foreign_key:

بالاتفاق، يفترض Rails أن العمود الذي يحمل المفتاح الخارجي في النموذج الآخر هو اسم النموذج مع إضافة بادئة id_، ويسمح لك خيار :foreign_key بتعيين اسم المفتاح الخارجي مباشرة:

class Supplier < ApplicationRecord
  has_one :account, foreign_key: "supp_id"
end

Quote

تنبيه:
على أي حال، لن ينشئ Rails أعمدة مفتاح خارجي لك، ستحتاج إلى تعريف صريح لهم كجزء من التهجيرات.

4.2.2.6 inverse_of:

يحدد خيار inverse_of: اسم ارتباط belongs_to والذي هو عكس هذا الارتباط، وهذا الخيار لا يعمل في التركيبة مع خيارات through: أو as:.

class Supplier < ApplicationRecord
  has_one :account, inverse_of: :supplier
end
 
class Account < ApplicationRecord
  belongs_to :supplier, inverse_of: :account
end

4.2.2.7 primary_key:

يفترض Rails أن العمود الذي يحمل المفتاح الرئيسي في هذا النموذج هو id، يمكنك تجاوز ذلك وتصريح المفتاح الرئيسي عن طريق خيار primary_key:

4.2.2.8 source:

يحدد خيار source: اسم ارتباط المصدر لارتباط has_one :through.

4.2.2.9 source_type:

يحدد خيار source_type: ارتباط المصدر لارتباط has_one :through الذي يمر عبر ارتباط متعدد الأشكال.

4.2.2.10 through:

يحدد خيار through: نموذج الضم والذي يتم من خلاله تنفيذ الاستعلام، تم الحديث حول has_one :through في وقت سابق من هذا الدليل.

4.2.2.11 validate:

إذا عُيّن خيار validate: إلى true، فسيتحقق من الكائنات المرتبطة كلما حفظت هذا الكائن، افتراضيا، قيمة هذا الخيار هي false، ولن يتحقق مع كائنات المرتبطة عند حفظ هذا الكائن.

4.2.3 نطاقات Scopes لـ belongs_to

في بعض الأحيان قد تحتاج إلى تخصيص الاستعلام المُستخدم من قبل has_one، ويمكن تحقيق هذه التخصيصات عن طريق كتلة scope، فعلى سبيل المثال:

class Supplier < ApplicationRecord
  has_one :account, -> { where active: true }
end

يمكنك استخدام أي من أساليب الاستعلامات القياسية داخل كتلة scope، وستجد تفاصيلها في الأسفل:

• where
• includes
• readonly
• select

4.2.3.1 where

يسمح لك أسلوب where بتحديد شروط الكائن المرتبط.

class Supplier < ApplicationRecord
  has_one :account, -> { where "confirmed = 1" }
end

4.2.3.2 includes

يمكنك استخدام أسلوب includes لتحديد الارتباطات من الدرجة الثانية التي تريد تحميلها (eager-loaded) عند استخدام هذا الارتباط، فعلى سبيل المثال، فكر في هذه النماذج:

class Supplier < ApplicationRecord
  has_one :account
end
 
class Account < ApplicationRecord
  belongs_to :supplier
  belongs_to :representative
end
 
class Representative < ApplicationRecord
  has_many :accounts
end

إذا كنت تسترد الممثلين مباشرة من المُوردين بشكل كثير (supplier.account.representative@)، فيمكنك جعل شيفرتك البرمجية أكثر كفاءة من خلال تضمين الممثلين إلى الارتباط من المُوردين إلى الحسابات:

class Supplier < ApplicationRecord
  has_one :account, -> { includes :representative }
end
 
class Account < ApplicationRecord
  belongs_to :supplier
  belongs_to :representative
end
 
class Representative < ApplicationRecord
  has_many :accounts
end

4.2.3.3 readonly

سيكون الكائن المرتبط للقراءة فقط عند استرداده عن طريق الارتباط إذا استخدمت readonly.

4.2.3.4 select

يسمح لك أسلوب select بتجاوز جملة SELECT (في SQL) والتي تُستخدم لاسترداد البيانات حول الكائن المرتبط، وبشكل افتراضي، سيسترد Rails جميع الأعمدة.

4.2.4 هل توجد أية كائنات مرتبطة؟

يمكنك معرفة هل توجد أية كائنات مرتبطة عن طريقة استخدام أسلوب ?association.nil

if @supplier.account.nil?
  @msg = "No account found for this supplier"
end

4.2.5 متى تحفظ الكائنات؟

عند تعيين كائن إلى ارتباط has_one، سيُحفظ ذلك الكائن بشكل تلقائي (من أجل تحديث مفتاحه الخارجي)، بالإضافة إلى ذلك، يُحفظ أي كائن أُستبدل بشكل تلقائي لأن المفتاح الخارجي سيتغير أيضا.
إذا فشلت عملية الحفظ بسبب أخطاء تحقق (validation)، فإن إعلان التعيين سيرجع false ويُلغى التعيين نفسه.
إذا لم يُحفظ (سترجع ?new_record قيمة false) الكائن الأب (الذي يعلن ارتباطhas_one )، فإن الكائنات الأبناء لن يُحفظوا أيضا، وسيُحفظون تلقائيا عند حفظ الكائن الأب.
إذا أردت تعيين كائن إلى ارتباط has_one بدون حفظ الكائن، استخدم أسلوب association.build.

وسنتابع في الدرس القادم شرح مرجع ارتباط has_many (الأساليب المضافة والخيارات).

المصدر:
توثيقات Ruby on Rails

تعرفنا في الدرس السابق على أهم الخدع، النصائح والتحذيرات وسنتابع في هذا الدرس مرجع الارتباط المفصّل.

4 مرجع الارتباط المفصّل

ستجد في الأقسام التالية تفاصيل حول كل نوع من أنواع الارتباط، بما في ذلك الأساليب التي تضيفها والخيارات التي يمكنك استخدامها عند إعلان الارتباط.

4.1 مرجع ارتباط belongs_to

ينشئ ارتباط belongs_to تطابق واحد لواحد (one-to-one) مع نموذج آخر، بمصطلحات قاعد البيانات، يعني هذا الارتباط أن هذا الصنف يحتوي على مفتاح خارجي، إذا كان الصنف الآخر يحتوي على مفتاح خارجي، فيجب عليك في هذه الحالة استخدام has_one بدلًا من ذلك.

4.1.1 أساليب مضافة بواسطة belongs_to

عند إعلان ارتباط belongs_to، فسيحصل الصنف المعلن على 5 أساليب مرتبطة بالارتباط:

• association
• association=(associate)
• ({} = build_association(attributes
• ({} = create_association(attributes
• ({} = create_association!(attributes
• reload_association

في جميع هذه النماذج، سيُستبدل الارتباط مع symbol الذي مُرر كمعامل أول إلى belongs_to، فعلى سبيل المثال، هذا الإعلان:

class Book < ApplicationRecord
  belongs_to :author
end

سيحصل كل مثيل نموذج Book على هذه الأساليب:

author
author=
build_author
create_author
create_author!
reload_author

اقتباس

ملاحظة:
يجب عليك استخدم بادئة _build عند تهيئة ارتباط has_one أو belongs_to لبناء الارتباط، بدلًا من أسلوب association.build الذي يستخدم لارتباطات has_many أو has_and_belongs_to_many، ولإنشاء واحد، استخدم بادئة _create.

4.1.1.1 association

يرجع أسلوب association الكائن المقترن إذا وجد، وإلا فسيُرجع nil.

@author = @book.author

إذا أُسترد الكائن من قاعدة البيانات لهذا الكائن، ستُرجع النسخة المخبئة، ولتجاوز هذا السلوك (وإجبار القراءة من قاعدة البيانات)، استدعي reload_association# في كائن الأب.

@author = @book.reload_author

4.1.1.2 (association=(associate

يعيّن أسلوب association= كائن مرتبط لهذا الكائن، في ما وراء الكواليس، يعني هذا استخراج المفتاح الأساسي من الكائن المرتبط وتعيين قيمة المفتاح الخارجي للكائن لنفس قيمته.

@book.author = @author

4.1.1.3 ({} = build_association(attributes 

يُرجع أسلوب build_association كائن جديد لنوع المرتبط، هذا الكائن سيُنشئ من السمات المُمرّرة وسيُعين الارتباط من خلال المفتاح الخارجي لكن لن بعد يحفظ بعد الكائن المرتبط.

@author = @book.build_author(author_number: 123,
                                  author_name: "John Doe")

4.1.1.4 ({} = create_association(attributes

سيرجع أسلوب create_association كائن جديد لنوع المرتبط، هذا الكائن سيُنشئ من السمات المُمررة وسيُعين الارتباط من خلال المفتاح الخارجي، وبمجرد تمرير جميع عمليات التحقيق validations المحددة على النموذج المرتبط، سيُحفظ الكائن المرتبط.

@author = @book.create_author(author_number: 123,
                                   author_name: "John Doe")

4.1.1.5 ({} = create_association!(attributes

يعمل كما create_association في الأعلى، لكنه يُصدر ActiveRecord::RecordInvalid إذا كان السجل record غير صالح.

4.1.2 خيارات لـ belongs_to

في حين يستخدم Rails افتراضات ذكية ستعمل بشكل صحيح في أغلب الأحيان، ستحتاج في بعض الأحيان إلى تخصيص مرجع سلوك ارتباط belongs_to، ويمكن تحقيق هذه التخصيصات بسهولة عن طريق تمرير الخيارات وكتل النطاق (scope) عند إنشاء الارتباط، فعلى سبيل المثال، هذا الارتباط يستخدم هذين الخيارين:

class Book < ApplicationRecord
  belongs_to :author, dependent: :destroy,
    counter_cache: true
end

يدعم ارتباط belongs_to هذه الخيارات:

• autosave:
• class_name:
• counter_cache:
• dependent:
• foreign_key:
• primary_key:
• inverse_of:
• polymorphic:
• touch:
• validate:
• optional:

4.1.2.1 autosave:

إذا عيّنت خيار autosave: إلى true، فسيحفظ Rails جميع أعضاء المحمّلين وسيدمر الأعضاء الذين وضع عليهم علامة التدمير كلما حفظت كائن الأب.

4.1.2.2 class_name:

إذا لم يكن بالإمكان اشتقاق اسم النموذج الآخر من اسم الارتباط، يمكنك استخدام خيار class_name: لتوفير اسم النموذج، فعلى سبيل المثال، إذا كان الكتاب ينتمي إلى المؤلف، لكن اسم فعلي للنموذج الذي يحتوي على المؤلفين هو Patron:

class Book < ApplicationRecord
  belongs_to :author, class_name: "Patron"
end

4.1.2.3 counter_cache:

يمكنك استخدام خيار counter_cache: لتجعل عملية العثور على عدد الكائنات التابعة أكثر كفاءة، على سبيل المثال هذه النماذج:

class Book < ApplicationRecord
  belongs_to :author
end
class Author < ApplicationRecord
  has_many :books
end

مع هذه الإعلانات، يتطلب طلب قيمة author.books.size@ الاتصال بقاعدة البيانات لتنفيذ استعلام (*)COUNT، ولنتجنب هذا الاتصال، يمكنك إضافة ذاكرة مؤقتة لتخزين العدد إلى نموذج الانتماء:

class Book < ApplicationRecord
  belongs_to :author, counter_cache: true
end
class Author < ApplicationRecord
  has_many :books
end

مع هذا الإعلان، سيُبقي Rails قيمة الذاكرة المؤقتة مُحدّثة، وسيجيب بتلك القيمة عند الطلب من أسلوب size.
على الرغم من تحديد خيار counter_cache: في النموذج الذي يتضمن إعلان belongs_to، يجب إضافة العمود الحالي إلى النموذج المرتبط (has_many)، في الحالة أعلاه، ستحتاج إلى إضافة عمود باسم books_count إلى نموذج Author.
يمكنك تجاوز اسم الافتراضي للعمود من خلال تحديد اسم العمود المخصص في إعلان counter_cache بدلا من true، فعلى سبيل المثال، لاستخدام count_of_books بدلا من books_count:

class Book < ApplicationRecord
  belongs_to :author, counter_cache: :count_of_books
end
class Author < ApplicationRecord
  has_many :books
end

اقتباس

ملاحظة:
تحتاج إلى تحديد خيار counter_cache: في جانب belongs_to من الارتباط.
تضاف أعمدة ذاكرة التخزين المؤقت إلى قائمة النموذج التي تحتوي على سمات القراءة فقط من خلال attr_readonly.

4.1.2.4 :dependent

إذا قمت بتعيين خيار dependent: إلى:

• destroy:، عند تدمير الكائن، ستُستدعى destroy على الكائنات المرتبطة.
• delete:، عند تدمير الكائن، ستُحذف جميع الكائنات المرتبطة بها مباشرة من قاعدة البيانات دون استدعاء أسلوب destroy.

اقتباس

تنبيه:
يجب عليك عدم تحديد هذا الخيار على ارتباط belongs_to المتصل مع ارتباط has_many على الصنف الآخر، لأنه قد يؤدي هذا إلى سجلات يتيمة في قاعدة البيانات.

4.1.2.5 foreign_key:

بالاتفاق، يفترض Rails أن العمود المستخدم لحمل المفتاح الخارجي في هذا النموذج هو اسم الارتباط مع إضافة بادئة id_، خيار foreign_key: يُتيح لك تعيين اسم المفتاح الخارجي مباشرة:

class Book < ApplicationRecord
  belongs_to :author, class_name: "Patron",
                        foreign_key: "patron_id"
end

اقتباس

ملاحظة:
في أي حال، لن ينشئ Rails عمود المفتاح الخارجي لك، ستحتاج إلى تعريفهم بشكل صريح كجزء من عمليات التهجير.

4.1.2.6 primary_key:

بالاتفاق، يفترض Rails أن عمود id يُستخدم لاحتواء المفتاح الرئيسي للجداول، ويسمح لك خيار primary_key: بتحديد عمود مختلف.
على سبيل المثال، إذا كان لدينا جدول users مع guid كمفتاح رئيسي، أردنا جدول todos منفصل لاحتواء المفتاح الخارجي user_id في عمود guid، ثم يمكننا استخدام primary_key لتحقيق ما يشابه هذا:

class User < ApplicationRecord
  self.primary_key = 'guid' # primary key is guid and not id
end
 
class Todo < ApplicationRecord
  belongs_to :user, primary_key: 'guid'
end

عند تنفيذ user.todos.create@ فستكون قيمة user_id في سجل todo@ كقيمة guid في user@.

4.1.2.7 inverse_of:

يحدد خيار inverse_of: اسم عكس هذا الارتباط وهي has_many أو has_one، وهذه لا تعمل في التركيبة مع خيارات polymorphic:

class Author < ApplicationRecord
  has_many :books, inverse_of: :author
end
 
class Book < ApplicationRecord
  belongs_to :author, inverse_of: :books
end

4.1.2.8 polymorphic:

يشير تمرير true إلى خيار polymorphic: إلى أن الارتباط متعدد الأشكال، وسنتحدث عن الارتباطات متعدد الأشكال لاحقا في هذا الدليل.

4.1.2.9 touch:

إذا عيّنت خيار touch: إلى true، فإن timestamp لـ updated_at أو updated_on في كائن المرتبط سيُعيّن إلى الوقت الحالي كلما حُفظ الكائن أو دُمر:

class Book < ApplicationRecord
  belongs_to :author, touch: true
end
 
class Author < ApplicationRecord
  has_many :books
end

في هذه الحالة، حفظ أو تدمير كتاب سيٌحدّث timestamp في المؤلف المرتبط به، يمكنك أيضًا تحديد سمة timestamp معينة للتحديث:

class Book < ApplicationRecord
  belongs_to :author, touch: :books_updated_at
end

4.1.2.10 validate:

إذا عيّنت خيار validate: إلى true، فسيتحقق (Validate) الكائنات المرتبطة كلما حفظت هذا الكائن. وهذا الخيار يساوي false بشكل افتراضي، ولن يتحقق الكائنات المرتبطة عند حفظ الكائن.

4.1.2.11 optional:

إذا عيّنت خيار optional: إلى true، فلن يتحقق من وجود الكائن المرتبط، وهذا الخيار false بشكل افتراضي.

4.1.3 نطاقات Scopes لـ belongs_to

في بعض الأحيان قد تحتاج إلى تخصيص الاستعلام المُستخدم من قبل belongs_to، ويمكن تحقيق هذه التخصيصات عن طريق كتلة scope، فعلى سبيل المثال:

class Book < ApplicationRecord
  belongs_to :author, -> { where active: true },
                        dependent: :destroy
end

يمكنك استخدام أي من أساليب الاستعلامات القياسية داخل كتلة scope، وستجد تفاصيل التالية في الأسفل:

• where
• includes
• readonly
• select

4.1.3.1 where

يسمح لك أسلوب where بتحديد شروط كائن المرتبط.

class book < ApplicationRecord
  belongs_to :author, -> { where active: true }
end

4.1.3.2 includes

يمكنك استخدام أسلوب includes لتحديد الارتباطات من الدرجة الثانية التي تريد تحميلها (eager-loaded) عند استخدام هذا الارتباط، فعلى سبيل المثال، فكر في هذه النماذج:

class LineItem < ApplicationRecord
  belongs_to :book
end
 
class Book < ApplicationRecord
  belongs_to :author
  has_many :line_items
end
 
class Author < ApplicationRecord
  has_many :books
end

إذا كنت تسترد المؤلفين مباشرة من سطر العناصر بشكل كثير (line_item.book.author@)، فيمكنك جعل شيفرتك البرمجية أكثر كفاءة من خلال تضمين المؤلفين إلى الارتباط من سطر العناصر إلى الكتب:

class LineItem < ApplicationRecord
  belongs_to :book, -> { includes :author }
end
 
class Book < ApplicationRecord
  belongs_to :author
  has_many :line_items
end
 
class Author < ApplicationRecord
  has_many :books
end

اقتباس

ملاحظة:
لا حاجة إلى استخدام includes للارتباطات الفورية، فإذا كان لديك Book belongs_to :author فيُحمل المؤلف (eager-loaded) بشكل تلقائي عند الحاجة.

4.1.3.3 readonly

سيكون الكائن المرتبط قابل للقراءة فقط عند استرداده عن طريق الارتباط إذا استخدمت readonly.

4.1.3.4 select

يسمح لك أسلوب select بتجاوز جملة SELECT (في SQL) والتي تُستخدم لاسترداد البيانات حول الكائن المرتبط، وبشكل افتراضي، سيسترد Rails جميع الأعمدة.

اقتباس

ملاحظة:
إذا استخدمت أسلوب select على ارتباط belongs_to، يجب عليك تعيين خيار :foreign_key لضمان صحّة النتائج.

4.1.4 هل توجد أية كائنات مرتبطة؟

يمكنك معرفة هل توجد أية كائنات مرتبطة عن طريقة استخدام أسلوب ?association.nil:

if @book.author.nil?
  @msg = "No author found for this book"
end

4.1.5 متى تُحفظ الكائنات؟

إن تعيين كائن إلى ارتباط belongs_to لن يحفظ الكائن بشكل تلقائي، ولن يحفظ كائن المرتبط أيضًا.

وسنتابع في الدرس القادم من هذه السلسلة الحديث عن مرجع ارتباط has_one

المصدر:
توثيقات Ruby on Rails

تعرفنا في الدرس السابق على الارتباطات وأنواعها وسنتابع في هذا الدرس أهم النصائح والخدع والتحذيرات.

3 نصائح، خدع وتحذيرات

يجب عليك معرفة هذه الأشياء لتستخدم ارتباطات Active Record بشكل أفضل وأكفأ في تطبيقات Rails:

• التحكم في التخزين المؤقت.
• تجنب تضارب الأسماء.
• تحديث المخطط.
• التحكم في نطاق (scope) الارتباط.
• الارتباطات ثنائية الاتجاه.

3.1 التحكم في التخزين المؤقت

تبنى جميع الارتباطات حول التخزين المؤقت، والذي يحافظ على نتيجة الاستعلام الأخيرة متاحة للعمليات القادمة، يتم تقاسم ذاكرة التخزين المؤقت عبر الأساليب، على سبيل المثال:

author.books                 # retrieves books from the database
author.books.size            # uses the cached copy of books
author.books.empty?          # uses the cached copy of books

لكن ماذا لو أردنا إعادة تحميل التخزين المؤقت، لأن البيانات قد تتغير عن طريق أجزاء اخرى من التطبيق؟ فقط أدعو إعادة التحميل في الارتباط:

author.books                 # retrieves books from the database
author.books.size            # uses the cached copy of books
author.books.reload.empty?   # discards the cached copy of books
                             # and goes back to the database

3.2 تجنب تضارب الأسماء

أنت لا تملك حرية كاملة في اختيار الاسم الذي تريده للارتباطات، لإن إنشاء الارتباط سيضيف أسلوب بهذا الاسم إلى النموذج، ومن السيئ إعطاء اسم ارتباط مستخدم بالفعل لمثيل أسلوب ActiveRecord::Base، فأسلوب الارتباط سيتجاوز أسلوب الأساس وسيكسر الأشياء، من الأسماء السيئة: attributes و connection.

3.3 تحديث المخطط

الارتباطات مفيدة للغاية لكنها ليست سحرية، فأنت مسؤول عن المحافظة على مخطط قاعدة البيانات ليطابق الارتباطات، وهذا يعني شيئين في الممارسة العملية حسب نوع الارتباطات التي تصنعها، فارتباطات belongs_to تحتاج إلى إنشاء مفاتيح خارجية، ولارتباطات has_and_belongs_to_many ستحتاج إلى إنشاء جدول الضم المناسب.

3.3.1 إنشاء مفاتيح خارجية لارتباطات belongs_to

عندما تعلن عن ارتباط belongs_to، ستحتاج إلى إنشاء مفاتيح خارجية حسب الحاجة، فعلى سبيل المثال، فكر في هذا النموذج:

class Book < ApplicationRecord
  belongs_to :author
end

يحتاج هذا الإعلان إلى أن يُدعم عن طريق مفتاح خارجي مناسب مُعلن في جدول books:

class CreateBooks < ActiveRecord::Migration[5.0]
  def change
    create_table :books do |t|
      t.datetime :published_at
      t.string   :book_number
      t.integer  :author_id
    end
  end
end

إذا أنشئت ارتباط بعد وقت من إنشاء النموذج الأساسي، ستحتاج إلى تذكر إنشاء تهجير add_column لتوفير مفتاح الخارجي الضروري.
من الممارسات الجيدة إضافة فهرس (index) إلى المفتاح الخارجي لتحسين أداء الطلبات وإضافة قيد على المفتاح الخارجي لضمان سلامة البيانات المرجعية:

class CreateBooks < ActiveRecord::Migration[5.0]
  def change
    create_table :books do |t|
      t.datetime :published_at
      t.string   :book_number
      t.integer  :author_id
    end
 
    add_index :books, :author_id
    add_foreign_key :books, :authors
  end
end

3.3.2 إنشاء جداول الضم لارتباطات has_and_belongs_to_many

إذا أنشئت ارتباط has_and_belongs_to_many، فستحتاج إلى إنشاء جدول الضم (joining table)، إذا لم يحدد اسم جدول الضم بشكل صريح عن طريق خيار join_table:، فسينشئ Active Record الاسم عن طريق استخدام الكتاب المعجمي لأسماء الصنف، فالضم بين نماذج المؤلف والكتاب سيُكوّن اسم جدول الضم بشكل افتراضي هو “authors_books”، لأن A تأتي قبل B في الترتيب المعجمي.

Quote

تنبيه:
تُحسب الأسبقية بين أسماء النماذج باستخدام العامل <=> للسلاسل النصية، وهذا يعني إذا كانت السلاسل النصية ذات أطوال مختلفة، وكانت كلا السلسلتين متساويتين مقارنة بالسلسلة الأقصر، فإن السلسلة النصية الأطول ذا أسبقية أعلى من السلسلة الأقصر، فعلى سبيل المثال، قد تملك جدول “paper_boxes” وجدول “papers” لإنشاء اسم جدول الضم “papers_paper_boxes” بسبب طول اسم “paper_boxes”، لكن في الحقيقة سيكون اسم جدول الضم هو “paper_boxes_papers” (لأن ‘_’ هي أقل من ‘s’ في أغلب الترميزات الشائعة).

مهما كان الاسم، يجب عليك إنشاء جدول الضم يدويا مع التهجير المناسب، فعلى سبيل المثال:

class Assembly < ApplicationRecord
  has_and_belongs_to_many :parts
end
 
class Part < ApplicationRecord
  has_and_belongs_to_many :assemblies
end

يجب أن تدعم هذه بالتهجير لإنشاء جدول assemblies_parts، والذي يجب أن يُنشئ دون مفتاح رئيسي:

class CreateAssembliesPartsJoinTable < ActiveRecord::Migration[5.0]
  def change
    create_table :assemblies_parts, id: false do |t|
      t.integer :assembly_id
      t.integer :part_id
    end
 
    add_index :assemblies_parts, :assembly_id
    add_index :assemblies_parts, :part_id
  end
end

مررنا id: false إلى create_table لأن الجدول لا يُمثل نموذج، وهذا ضروري للارتباط ليعمل بشكل صحيح.
قد تلاحظ تصرفات غريبة في ارتباط has_and_belongs_to_many مثل مُعرّفات نموذج سيئة أو استثناءات حول تضارب المعرّفات، لكنها نادرا ما تحدث.
يمكنك استخدام أسلوب create_join_table أيضًا.

class CreateAssembliesPartsJoinTable < ActiveRecord::Migration[5.0]
  def change
    create_join_table :assemblies, :parts do |t|
      t.index :assembly_id
      t.index :part_id
    end
  end
end

3.4 التحكم في نطاق scope الارتباط

تبحث الارتباطات افتراضيا عن الكائنات ضمن نطاق الوحدة (module) الحالية، وهذا جيد عندما تعلن عن نماذج Active Record ضمن الوحدة، فعلى سبيل المثال:

module MyApplication
  module Business
    class Supplier < ApplicationRecord
       has_one :account
    end
 
    class Account < ApplicationRecord
       belongs_to :supplier
    end
  end
end

وهذا سيعمل بشكل صحيح، لأن كل من صنف المُورّد والحساب تم تعريفهما داخل نفس النطاق، لكن الشيفرة البرمجية التالية لن تعمل، لأنه عُرّف المُورّد والحساب في نطاقات مختلفة:

module MyApplication
  module Business
    class Supplier < ApplicationRecord
       has_one :account
    end
  end
 
  module Billing
    class Account < ApplicationRecord
       belongs_to :supplier
    end
  end
end

لربط نموذج مع نموذج في مساحة اسم (namespace) مختلفة يجب عليك تحديد اسم الصنف كاملا في إعلان الارتباط:

module MyApplication
  module Business
    class Supplier < ApplicationRecord
       has_one :account,
        class_name: "MyApplication::Billing::Account"
    end
  end
 
  module Billing
    class Account < ApplicationRecord
       belongs_to :supplier,
        class_name: "MyApplication::Business::Supplier"
    end
  end
end

3.5 الارتباطات ثنائية الاتجاه

من الطبيعي أن تعمل الارتباطات في كلا الاتجاهين، وهذا الأمر يتطلب إعلان في نموذجين مختلفين:

class Author < ApplicationRecord
  has_many :books
end
 
class Book < ApplicationRecord
  belongs_to :author
end

سيحاول Active Record تلقائيا معرفة أن هذيّن النموذجين يشتركان في ارتباط ثنائي الاتجاه بناءا على اسم الارتباط، وبهذه الطريقة سيحمّل Active Record نسخة واحدة من كائن Author وبذلك سيصبح تطبيقك أكثر كفاءة ويمنع البيانات غير المتناسقة:

a = Author.first
b = a.books.first
a.first_name == b.author.first_name # => true
a.first_name = 'David'
a.first_name == b.author.first_name # => true

يدعم Active Record التعرف التلقائي لأغلب الارتباطات مع الأسماء القياسيّة، ومع ذلك لن يُعرّف Active Record الارتباطات ثنائية الاتجاه تلقائيا إذا احتوت على أي من الخيارات التالية:

• conditions:
• through:
• polymorphic:
• class_name:
• foreign_key

على سبيل المثال، فكر في إعلان النماذج التالية:

class Author < ApplicationRecord
  has_many :books
end
 
class Book < ApplicationRecord
  belongs_to :writer, class_name: 'Author', foreign_key: 'author_id'
end

لن يتعرف Active Record تلقائيا على الارتباط ثنائي الاتجاه:

a = Author.first
b = a.books.first
a.first_name == b.writer.first_name # => true
a.first_name = 'David'
a.first_name == b.writer.first_name # => false

يوفر Active Record خيار :inverse_of حتى تتمكن من الإعلان الارتباطات ثنائية الاتجاه بشكل صريح:

class Author < ApplicationRecord
  has_many :books, inverse_of: 'writer'
end
 
class Book < ApplicationRecord
  belongs_to :writer, class_name: 'Author', foreign_key: 'author_id'
end

من خلال تضمين خيار :inverse_of في إعلان ارتباط has_many، سيتعرّف Active Record على ارتباط ثنائي الاتجاه:

a = Author.first
b = a.books.first
a.first_name == b.writer.first_name # => true
a.first_name = 'David'
a.first_name == b.writer.first_name # => true

توجد بعض القيود على دعم inverse_of: :

• لا تعمل مع ارتباطات through:
• لا تعمل مع ارتباطات polymorphic:
• لا تعمل مع ارتباطات as:

وسنتابع في الدرس القادم التعرّف على مرجع الارتباط المفصّل.

المصدر:
توثيقات Ruby on Rails

سنتعرّف في سلسلة الدروس هذه والتي تبدأ بهذا الدرس على ارتباطات Active Record في روبي أند ريلز وسنبدأ أولًا بمعرفة لماذا الارتباطات:

1 لماذا الارتباطات Associations؟

في Rails، الارتباط association هو اتصال بين نموذجي Active Record. لماذا نحتاج إلى هذه الارتباطات بين النماذج؟ وذلك لأن العمليات المشتركة ستصبح أبسط وأسهل في الشيفرة البرمجية، على سبيل المثال، اعتبر أن تطبيق Rails بسيط يتضمن نموذج للمؤلفين ونموذج للكتب، كل مؤلف قد يملك العديد من الكتب، وبدون الارتباطات، سيشبه إعلان النموذج هذا:

class Author < ApplicationRecord
end
 
class Book < ApplicationRecord
end

الآن، لنفترض أننا نريد إضافة كتاب جديد للمؤلف الحالي:

@book = Book.create(published_at: Time.now, author_id: @author.id)

أو حذف المؤلف مع جميع كتبه:

@books = Book.where(author_id: @author.id)
@books.each do |book|
  book.destroy
end
@author.destroy

باستخدام ارتباطات Active Record، يمكننا تبسيط هذه العملية (وغيرها) عن طريق إعلان لـ Rails نخبره بوجود اتصال بين النموذجين، وهذه الشيفرة البرمجية معدلة لإعداد المؤلفين والكتب:

class Author < ApplicationRecord
  has_many :books, dependent: :destroy
end
 
class Book < ApplicationRecord
  belongs_to :author
end

وبهذا، ستصبح عملية إنشاء كتاب لمؤلف معين أسهل:

@book = @author.books.create(published_at: Time.now)

بالإضافة إلى أن عملية حذف المؤلف مع جميع كتبه أسهل بكثير:

@author.destroy

لمزيد من المعلومات حول الأنواع المختلفة للارتباطات، اقرأ القسم التالي من هذا الدليل، وستجد بعدها بعض النصائح والحيل للعمل مع الارتباطات، ومن ثم مرجع كامل للنماذج وخيارات الارتباطات في Rails.

2 أنواع الارتباطات Associations

يدعم Rails ستة أنواع من الارتباطات Associations:

• belongs_to
• has_one
• has_many
• has_many :through
• has_one :through
• has_and_belongs_to_many

تنفّذ الارتباطات Association باستخدام نداءات نمط ماكرو (macro-style) بحيث يمكنك إضافة ميزات إلى نماذج، فعلى سبيل المثال، من خلال إعلان أن نموذج ينتمي belongs_to إلى آخر، ستجعل Rails يحافظ على بيانات المفتاح الرئيسي والمفتاح الخارجي (Primary Key-Foreign Key) بين مثيلات النموذجين، ويمكنك الحصول على عدد الأساليب المضافة إلى نموذجك.

في ما تبقى من هذا الدليل، ستتعلم كيف تُعلن وتستخدم أشكال مختلفة من الارتباطات، لكن أولا، مقدمة قصيرة إلى الحالات التي تتناسب معها كل نوع من الارتباطات.

2.1 ارتباط belongs_to

يعيّن ارتباط belongs_to اتصال واحد لواحد (one-to-one) مع نموذج آخر، بحيث أن كل مثيل للنموذج المعلن “يرتبط” بمثيل واحد للنموذج الآخر، فعلى سبيل المثال، إذا كان التطبيق يتضمن مؤلفين وكتب وكل كتاب يرتبط فقط إلى مؤلف واحد، يمكنك إعلان نموذج الكتاب كالتالي:

class Book < ApplicationRecord
  belongs_to :author
end

Quote

ملاحظة: يجب أن تستخدم ارتباطات belongs_to صيغة المفرد، فإذا استخدمت صياغة الجمع في المثال أعلاه لارتباط المؤلف مع نموذج الكتاب، ستظهر لك رسالة "uninitialized constant Book::Authors" وذلك لأن Rails يستنتج اسم الصنف من اسم الارتباط، إذا جُمع اسم الارتباط عن طريق الخطأ فالأصناف المستنسخة ستجمع عن طريق الخطأ.

عملية التهجير ستشبه هذه:

class CreateBooks < ActiveRecord::Migration[5.0]
  def change
    create_table :authors do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :books do |t|
      t.belongs_to :author, index: true
      t.datetime :published_at
      t.timestamps
    end
  end
end

2.2 ارتباط has_one

يعيّن ارتباط has_one أيضا اتصال واحد لواحد (one-to-one) مع نموذج آخر، لكن مع دلالات (semantics) -وعواقب- مختلفة، فيشير هذا الارتباط أن كل مثيل للنموذج يحتوي أو يمتلك مثيل لنموذج آخر فعلى سبيل المثال، إذا يملك كل مُورّد في تطبيقك حساب واحد فقط، سيشبه إعلان نموذج المورد هذا:

class Supplier < ApplicationRecord
  has_one :account
end

عملية التهجير ستشبه هذه:

class CreateSuppliers < ActiveRecord::Migration[5.0]
  def change
    create_table :suppliers do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :accounts do |t|
      t.belongs_to :supplier, index: true
      t.string :account_number
      t.timestamps
    end
  end
end

بناءََ على حالة الاستخدام، ستحتاج إلى إنشاء فهرس فريد و/أو إلى قيد مفتاح خارجي (foreign key) على عمود المُورّد لجدول الحسابات، في هذه الحالة، سيشبه تعريف العمود لهذا:

create_table :accounts do |t|
  t.belongs_to :supplier, index: { unique: true }, foreign_key: true
  # ...
end

2.3 ارتباط has_many

يشير ارتباط has_many إلى اتصال واحد إلى الكثير (one-to-many) مع نموذج آخر، ستجد في الكثير من الأحيان هذا الارتباط في الجانب الآخر لارتباط belongs_to، وهذا الارتباط يشير إلى أن كل مثيل للنموذج يملك صفر مثيل أو أكثر للنموذج الآخر، فعلى سبيل المثال، في التطبيق الذي يحتوي على المؤلفين وكتب، يمكنك الإعلان عن نموذج المؤلف كالتالي:

class Author < ApplicationRecord
  has_many :books
end

Quote

ملاحظة: يُجمع – صياغة الجمع - اسم النموذج الآخر عند إعلان ارتباط has_many.

عملية التهجير ستشبه هذه:

class CreateAuthors < ActiveRecord::Migration[5.0]
  def change
    create_table :authors do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :books do |t|
      t.belongs_to :author, index: true
      t.datetime :published_at
      t.timestamps
    end
  end
end

2.4 ارتباط has_many :through

يُستخدم ارتباط has_many :through لإنشاء اتصال كثير إلى كثير(many-to-many) مع نموذج آخر، فهذا النموذج يشير إلى أن النموذج المُعلن يمكن أن يقابل صفر مثيل أو أكثر من نموذج آخر من خلال نموذج ثالث، فعلى سبيل المثال، فكر في العمل الطبي حيث يحدد المرضى مواعيد لرؤية الأطباء، فسيُعلن الارتباط كالتالي:

class Physician < ApplicationRecord
  has_many :appointments
  has_many :patients, through: :appointments
end
 
class Appointment < ApplicationRecord
  belongs_to :physician
  belongs_to :patient
end
 
class Patient < ApplicationRecord
  has_many :appointments
  has_many :physicians, through: :appointments
end

عملية التهجير ستشبه هذه:

class CreateAppointments < ActiveRecord::Migration[5.0]
  def change
    create_table :physicians do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :patients do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :appointments do |t|
      t.belongs_to :physician, index: true
      t.belongs_to :patient, index: true
      t.datetime :appointment_date
      t.timestamps
    end
  end
end

يمكنك إدارة مجموعة نماذج المنضمّة عن طريق أساليب ارتباط has_many، فعلى سبيل المثال، إذا عيّنت هذا:

physician.patients = patients

فإنه سينشئ النماذج المنضمّة تلقائيا للكائنات المرتبطة حديثا، إذا كان بعضها موجود سابقا وفُقِد حاليا، فستُحذف صفوف الضم الخاصة به تلقائيا.

Quote

تنبيه: تحذف النماذج المنضمّة تلقائيا بشكل مباشر، فلن تشتغل دالة الاستدعاء للتدمير.

يمكنك الاستفادة من ارتباط has_many :through لإنشاء "اختصارات” من خلال ارتباطات has_many متداخلة، فعلى سبيل المثال، إذا كان مستند يملك أقسام عديدة، ويحتوي القسم على فقرات، فقد تحتاج في بعض الأحيان إلى الحصول على مجموعة بسيطة من جميع الفقرات في المستند، ويمكنك إنشاء ذلك عن طريق:

class Document < ApplicationRecord
  has_many :sections
  has_many :paragraphs, through: :sections
end
 
class Section < ApplicationRecord
  belongs_to :document
  has_many :paragraphs
end
 
class Paragraph < ApplicationRecord
  belongs_to :section
end

سيفهم Rails هذا الآن عن طريق محدد through: :sections:

@document.paragraphs

2.5 ارتباط has_one :through

تنشئ ارتباطات has_one :through اتصال واحد لواحد (one-to-one) مع نموذج آخر، هذا الارتباط يشير إلى أن النموذج المُعلن عنه يمكن أن يقابل مع مثيل من نموذج آخر من خلال نموذج آخر، على سبيل المثال، إذا كان يملك كل مُورّد حساب واحد، وكل حساب مرتبط بسجل حساب واحد، فسيكون نموذج المُورّد كالتالي:

class Supplier < ApplicationRecord
  has_one :account
  has_one :account_history, through: :account
end
 
class Account < ApplicationRecord
  belongs_to :supplier
  has_one :account_history
end
 
class AccountHistory < ApplicationRecord
  belongs_to :account
end

عملية التهجير ستشبه هذه:

class CreateAccountHistories < ActiveRecord::Migration[5.0]
  def change
    create_table :suppliers do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :accounts do |t|
      t.belongs_to :supplier, index: true
      t.string :account_number
      t.timestamps
    end
 
    create_table :account_histories do |t|
      t.belongs_to :account, index: true
      t.integer :credit_rating
      t.timestamps
    end
  end
end

2.6 الارتباط has_and_belongs_to_many

ينشئ ارتباط has_and_belongs_to_many اتصال الكثير إلى الكثير many-to-many مباشر مع نموذج آخر بدون تدخل نموذج ثالث، فعلى سبيل المثال، إذا كان تطبيقك يحتوي على تجميعات وأجزاء، ستجد أجزاء عديدة مع كل تجميع وكل جزء يظهر في الكثير من التجميعات، فيمكنك إعلان هذا النموذج كالتالي:

class Assembly < ApplicationRecord
  has_and_belongs_to_many :parts
end
 
class Part < ApplicationRecord
  has_and_belongs_to_many :assemblies
end

عملية التهجير ستشبه هذه:

class CreateAssembliesAndParts < ActiveRecord::Migration[5.0]
  def change
    create_table :assemblies do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :parts do |t|
      t.string :part_number
      t.timestamps
    end
 
    create_table :assemblies_parts, id: false do |t|
      t.belongs_to :assembly, index: true
      t.belongs_to :part, index: true
    end
  end
end

2.7 الاختيار بين belongs_to و has_one

إذا أردت إنشاء علاقة واحد إلى واحد (one-to-one) بين نموذجين، فستحتاج إلى إضافة belongs_to to إلى أحدهم و has_one إلى الآخر، فكيف ستعرف لمن تضيف هذا؟
يمكنك تمييز ذلك عن طريق المكان الذي وضعت فيه المفتاح الخارجي (ستكون في الجدول الصنف الذي أعلنت فيه ارتباط belongs_to)، لكن يجب عليك أن تفكر في معنى الفعلي للبيانات، فعلاقة has_one تعني أنه يوجد شيء خاص بك، أي أن جزء منه يعود لك، فعلى سبيل المثال، من المنطقي القول بأن المُورّد يملك حساب على أن الحساب يملك مُورّد، وهذا يعني أن العلاقة الصحيحة مشابهة لهذه:

class Supplier < ApplicationRecord
  has_one :account
end
 
class Account < ApplicationRecord
  belongs_to :supplier
end

عملية التهجير ستشبه هذه:

class CreateSuppliers < ActiveRecord::Migration[5.0]
  def change
    create_table :suppliers do |t|
      t.string :name
      t.timestamps
    end
 
    create_table :accounts do |t|
      t.integer :supplier_id
      t.string  :account_number
      t.timestamps
    end
 
    add_index :accounts, :supplier_id
  end
end

Quote

ملاحظة: يمكنك جعل اسم المفتاح الخارجي واضح وصريح عن طريق استخدام t.integer :supplier_id، في الإصدار Rails الحالي، يمكنك استخدام t.references :supplier بدلاً من ذلك.

2.8 الاختيار بين has_many :through و has_and_belongs_to_many

يوفر Rails طريقتين لإعلان علاقة الكثير إلى الكثير (many-to-many) بين النماذج، أبسط طريقة هي عن طريق استخدام has_and_belongs_to_many، والتي تمكنك من إنشاء هذا الارتباط مباشرة:

class Assembly < ApplicationRecord
  has_and_belongs_to_many :parts
end
 
class Part < ApplicationRecord
  has_and_belongs_to_many :assemblies
end

الطريقة الثانية هي عن طريق استخدام has_many :through لجعل الارتباط غير مباشرة، عن طريق ضم نموذج:

class Assembly < ApplicationRecord
  has_many :manifests
  has_many :parts, through: :manifests
end
 
class Manifest < ApplicationRecord
  belongs_to :assembly
  belongs_to :part
end
 
class Part < ApplicationRecord
  has_many :manifests
  has_many :assemblies, through: :manifests
end

ببساطة، إذا أردت العمل مع نموذج العلاقة ككيان مستقل، يجب عليك إنشاء علاقة has_many :through، وإذا لم تحتاج إلى القيام بأي شيء مع نموذج العلاقة، سيكون من الأسهل إنشاء علاقة has_and_belongs_to_many (لا تنسى إنشاء جدول الضم joining table في قاعدة البيانات).
يجب عليك استخدام has_many :through إذا احتجت إلى عمليات تحقق validations، دوال استدعاء callbacks أو سمات attributes إضافيَة في نموذج الضم.

2.9 ارتباطات متعددة الأشكال Polymorphic Associations

من المواضيع المتقدمة قليلا في الارتباطات، هي الارتباطات متعددة الأشكال، فعن طريقها، يمكن للنموذج أن يرتبط بأكثر من نموذج بارتباط واحد، فعلى سبيل المثال، قد تملك نموذج صورة التي تنتمي إلى نموذج الموظف أو إلى نموذج المنتج، ويمكنك الإعلان عن ذلك عن طريق التالي:

class Picture < ApplicationRecord
  belongs_to :imageable, polymorphic: true
end
 
class Employee < ApplicationRecord
  has_many :pictures, as: :imageable
end
 
class Product < ApplicationRecord
  has_many :pictures, as: :imageable
end

فكر في إعلان belongs_to متعدد الأشكال على أنه إنشاء لواجهة يمكن لأي نموذج آخر أن يستخدمها، من مثيل نموذج Employee، يمكنك استرداد مجموع من الصور عن طريق:

 @employee.pictures.

وبنفس الطريقة يمكنك استرداد product.pictures@.
إذا كنت تملك مثيل من نموذج الصورة، فيمكنك الحصول على الأب (parent) عن طريق picture.imageable@، ولتحقيق ذلك، تحتاج إلى إعلان كل من عمود مفتاح خارجي وعمود النوع في النموذج الذي أعلنت فيه واجهة متعددة الأشكال:

class CreatePictures < ActiveRecord::Migration[5.0]
  def change
    create_table :pictures do |t|
      t.string  :name
      t.integer :imageable_id
      t.string  :imageable_type
      t.timestamps
    end
 
    add_index :pictures, [:imageable_type, :imageable_id]
  end
end

يمكن تبسيط عملية التهجير عن طريق استخدام t.references:

class CreatePictures < ActiveRecord::Migration[5.0]
  def change
    create_table :pictures do |t|
      t.string :name
      t.references :imageable, polymorphic: true, index: true
      t.timestamps
    end
  end
end

2.10 ضم ذاتي Self Joins

عند تصميم نموذج بيانات، ستجد في بعض الأحيان أن العلاقة يجب أن تكون مرتبطة بنفسها، فعلى سبيل المثال، قد تريد تخزين جميع الموظفين في نموذج قاعدة بيانات واحدة، لكن يجب تقدر أيضا على تتبع العلاقات مثل علاقة المدير بالمرؤوسين، وهذه الحالة يمكن إنشاءها عن طريق ارتباطات الضم الذاتي:

class Employee < ApplicationRecord
  has_many :subordinates, class_name: "Employee",
                          foreign_key: "manager_id"
 
  belongs_to :manager, class_name: "Employee"
end

مع هذا الإعداد، يمكنك استرداد employee.subordinates@ و employee.manager@.
في عمليات التهجير/المخطط، ستحتاج إلى إضافة عمود المرجع إلى نفس النموذج.

class CreateEmployees < ActiveRecord::Migration[5.0]
  def change
    create_table :employees do |t|
      t.references :manager, index: true
      t.timestamps
    end
  end
end

وسنتابع التعرّف على الإرتباطات في Active Record في الدروس اللاحقة.

المصدر:
توثيقات Ruby on Rails

ستتعرّف في هذا الدرس على دورة حياة كائنات Active Record، وستتعلم:

• دورة حياة كائنات Active Record.
• كيف تنشئ أساليب دوال الاستدعاء (callback methods) التي تستجيب إلى أحداث في دورة حياة الكائن.
• كيف تنشئ أصناف خاصة التي تجمع السلوك المشترك لدوال الاستدعاء (callbacks).

1- دورة حياة الكائن

يمكن إنشاء، تحديث وتدمير الكائنات أثناء عمل تطبيق Rails، ويوفر Active Record طُرق تُمكنك من التحكم بالتطبيق وبياناته في دورة حياة الكائن .
يسمح لك دوال الاستدعاء بإطلاق منطقي (trigger logic) قبل أو بعد تغيير حالة الكائن.

2- نظرة عامة على دوال الاستدعاء callbacks

دوال الاستدعاء (callbacks) هي أساليب تُستدعى في لحظات معينة من دورة حياة الكائن وتمكنك من كتابة شيفرة برمجية تعمل عند إنشاء، حفظ، تحديث، حذف، تحقق من صحة أو تحميل كائن Active Record من قاعدة البيانات.

2-1 تسجيل دوال الاستدعاء

تحتاج إلى تسجيل دوال الاستدعاء المتوفر حتى تتمكن من استخدامه، فيمكنك وضع دوال الاستدعاء كأساليب عادية، واستخدام أسلوب صنف نمط ماكرو (macro-style) لتسجيلهم كدوال استدعاء:

class User < ApplicationRecord
  validates :login, :email, presence: true
 
  before_validation :ensure_login_has_a_value
 
  private
    def ensure_login_has_a_value
      if login.nil?
        self.login = email unless email.blank?
      end
    end
end

يمكن لأساليب صنف نمط ماكرو (macro-style) تلقي كتلة (block) لذلك استخدم هذا النمط إذا كانت الشيفرة البرمجية داخل الكتلة قصيرة بحيث يمكن وضعها في سطر واحد:

class User < ApplicationRecord
  validates :login, :email, presence: true
 
  before_create do
    self.name = login.capitalize if name.blank?
  end
end

يمكنك تسجيل دوال الاستدعاء ليعمل فقط على بعض أحداث دورة حياة الكائن:

class User < ApplicationRecord
  before_validation :normalize_name, on: :create
 
  # :on takes an array as well
  after_validation :set_location, on: [ :create, :update ]
 
  private
    def normalize_name
      self.name = name.downcase.titleize
    end
 
    def set_location
      self.location = LocationService.query(self)
    end
end

من الممارسات الجيدة أن تعلن أساليب دوال الاستدعاء كخاص، لأنه يمكن استدعاؤه من خارج النموذج (Model) إذا كان عامََا وبهذا تنتهك مبدأ تغليف الكائن (object encapsulation).

3- دوال الاستدعاء المتوفرة

هذه قائمة بجميع دوال استدعاء Active Record المتوفر وهو مرتب بنفس ترتيب استدعاءه خلال العمليات:

3-1 إنشاء كائن

• before_validation
• after_validation
• before_save
• around_save
• before_create
• around_create
• after_create
• after_save
• after_commit/after_rollback

3-2 تحديث كائن

• before_validation
• after_validation
• before_save
• around_save
• before_update
• around_update
• after_update
• after_save
• after_commit/after_rollback

3-3 تدمير كائن

• before_destroy
• around_destroy
• after_destroy
• after_commit/after_rollback

اقتباس

تحذير:
تعمل after_save عند الإنشاء والتحديث لكن دائما بعد دوال الاستدعاء after_create و after_update مهما كان ترتيب تنفيذ نداءات ماكرو (macro calls).

3-4 after_initialize و after_find

ستُستدعى دالة الاستدعاء after_initialize عند إنشاء كائن Active Record، إما مباشرة عن طريق new أو عند تحميل السجل record من قاعدة البيانات، ومن المستحسن تجنب الحاجة إلى تجاوز إنشاء أسلوب Active Record مباشرة.
ستُستدعى دالة الاستدعاء after_find في كل مرة يُحمّل فيها Active Record سجل من قاعدة البيانات، وستُستدعى after_find قبل after_initialize إذا تم تعريفهما.

لا يملك دوال الاستدعاء after_initialize وafter_find نظرائهم من نوع before_*، لكن يمكن تسجيلهم كباقي دوال الاستدعاء Active Record.

class User < ApplicationRecord
  after_initialize do |user|
    puts "You have initialized an object!"
  end
 
  after_find do |user|
    puts "You have found an object!"
  end
end
 
>> User.new
You have initialized an object!
=> #<User id: nil>
 
>> User.first
You have found an object!
You have initialized an object!
=> #<User id: 1>

3-5 after_touch

ستُستدعى دالة الاستدعاء after_touch كلما يُلمس (touch) كائن Active Record.

class User < ApplicationRecord
  after_touch do |user|
    puts "You have touched an object"
  end
end
 
>> u = User.create(name: 'Kuldeep')
=> #<User id: 1, name: "Kuldeep", created_at: "2013-11-25 12:17:49", updated_at: "2013-11-25 12:17:49">
 
>> u.touch
You have touched an object
=> true

يمكن استخدام هذه الدالة جنبا إلى جنب مع belongs_to:

class Employee < ApplicationRecord
  belongs_to :company, touch: true
  after_touch do
    puts 'An Employee was touched'
  end
end
 
class Company < ApplicationRecord
  has_many :employees
  after_touch :log_when_employees_or_company_touched
 
  private
  def log_when_employees_or_company_touched
    puts 'Employee/Company was touched'
  end
end
 
>> @employee = Employee.last
=> #<Employee id: 1, company_id: 1, created_at: "2013-11-25 17:04:22", updated_at: "2013-11-25 17:05:05">
 
# triggers @employee.company.touch
>> @employee.touch
Employee/Company was touched
An Employee was touched
=> true

4- تشغيل دوال الاستدعاء

هذه أساليب إطلاق (trigger) دوال الاستدعاء:

• create
• create!
• destroy
• destroy!
• destroy_all
• save
• save!
• save(validate: false)
• toggle!
• update_attribute
• update
• update!
• Valid?

بالإضافة إلى ذلك، تُطلق (trigger) دالة الاستدعاء after_find عن طريق أساليب finder التالية:

• all
• first
• find
• find_by
• find_by_*
• find_by_*!
• find_by_sql
• last

تعمل دالة الاستدعاء after_initialize في كل مرة ينشئ فيها كائن صنف class جديد.

اقتباس

ملاحظة:
أساليب find_by_* و find_by_*! هي finders حيوية تُولد تلقائيا لكل سمة، للمزيد من المعلومات راجع قسم Dynamic finders.

5- تجاوز دوال الاستدعاء

كما هو الحال مع عمليات التحقق (validation)، من الممكن أيضا تخطي دوال الاستدعاء عن طريق الأساليب التالية:

• decrement
• decrement_counter
• delete
• delete_all
• increment
• increment_counter
• toggle
• touch
• update_column
• update_columns
• update_all
• update_counters

يجب استخدام هذه الأساليب بحذر، لأنه قد يُحتفظ بقواعد الأعمال (generated) الهامة ومنطق التطبيق في دوال الاستدعاء، وقد يؤدي تجاوزها دون فهم الآثار المحتملة إلى بيانات غير صالحة.

6- وقف التنفيذ

عند بدء تسجيل دوال استدعاء جديد لنماذجك، سيكون في قائمة الانتظار للتنفيذ، وستشمل هذه القائمة جميع عمليات تحقق (validations) النموذج الخاص بك، ودوال الاستدعاء المسجلة وعمليات قاعدة البيانات التي ستُنفّذ.
تُلف سلسلة (chain) دالة الاستدعاء بشكل كامل في العملية (transaction)، إذا أصدرت أي دالة استدعاء استثناء (exception)، فستتوقف السلسلة التي تعمل و يصدر ROLLBACK، وإذا أردت تعمد إيقاف السلسلة، استخدم:

throw :abort

اقتباس

تحذير:
سيعاد إصدار أي استثناء (ما عدا ActiveRecord::Rollback أو ActiveRecord::RecordInvalid) عن طريق Rails بعد إيقاف سلسلة دالة الاستدعاء.
قد يكسر أي استثناء ماعدا ActiveRecord::Rollback أو ActiveRecord::RecordInvalid شيفرتك البرمجية التي لا تتوقع إصدار استثناء مثل أساليب save و update_attributes (والتي تُرجع في العادة قيمة منطقية true أو false).

7- دوال استدعاء علائقي

يعمل دوال الاستدعاء من خلال علاقات النموذج model، ويمكن تعريفه عن طريقه، لنفترض أن المستخدم لديه مقالات عديدة، ويجب حذف مقالات المستخدم في حالة حذف المستخدم، لنضف دالة استدعاء after_destroy إلى نموذج User لترتبط علائقيا بنموذج Model:

class User < ApplicationRecord
  has_many :articles, dependent: :destroy
end
 
class Article < ApplicationRecord
  after_destroy :log_destroy_action
 
  def log_destroy_action
    puts 'Article destroyed'
  end
end
 
>> user = User.first
=> #<User id: 1>
>> user.articles.create!
=> #<Article id: 1, user_id: 1>
>> user.destroy
Article destroyed
=> #<User id: 1>

8- دوال الاستدعاء المشروط

كما هو الحال مع عمليات التحقق Validation، يمكن أيضا جعل أسلوب دالة الاستدعاء مشروط بشرط معين عن طريق استخدام خيارات :if و :unless والتي تأخذ رمز (symbol) أو Proc أو مصفوفة (Array).
يمكنك استخدام خيار :if عندما تريد تحديد شروط استدعاء دالة الاستدعاء، وإذا أردت وضع شروط لعدم استدعاء دالة الاستدعاء يمكنك استخدام :unless.

8-1 استخدام :if و :unless مع Symbol

يمكنك ربط خيارات :if و :unless مع رمز (Symbol) مطابق لاسم الأسلوب الذي سيُستدعى قبل دالة الاستدعاء.
لن تُنفّذ دالة الاستدعاء عند استخدام خيار :if إذا ارجع الأسلوب false، وعند استخدام :unless لن تُنفّذ دالة الاستدعاء إذا أرجع الأسلوب true، وهذا الخيار هو الأكثر شيوعا.
من الممكن أيضا باستخدام هذا الشكل من التسجيل تسجيل predicates مختلفة، التي يتم استدعاؤها للتحقق ما إذا كان يجب تنفيذ دالة الاستدعاء.

class Order < ApplicationRecord
  before_save :normalize_card_number, if: :paid_with_card?
End

8-2 استخدام :if و :unless مع Proc

أخيرا، من الممكن ربط :if و :unless مع كائن Proc، وهذا الخيار هو الأنسب عند كتابة أساليب تحقق (validation) قصيرة، وفي العادة من سطر واحد:

class Order < ApplicationRecord
  before_save :normalize_card_number,
    if: Proc.new { |order| order.paid_with_card? }
end

8-3 شروط متعددة لدوال الاستدعاء

عند كتابة دوال استدعاء شرطي، من الممكن المزج بين :if و :unless في نفس إعلان دالة الاستدعاء:

class Comment < ApplicationRecord
  after_create :send_email_to_author, if: :author_wants_emails?,
    unless: Proc.new { |comment| comment.article.ignore_comments? }
end

9- أصناف دالة الاستدعاء

في بعض الأحيان، تكون أساليب دالة الاستدعاء التي ستكتبها مفيدة وملائمة لإعادة استخدامها من قبل نماذج أخرى، لذا يوفر Active Record إمكانية إنشاء أصناف تغلف أساليب دالة الاستدعاء، لذا يصبح من السهل إعادة استخدامها.
هذا مثال أنشئنا فيه صنف مع دالة استدعاء after_destroy لنموذج PictureFile:

class PictureFileCallbacks
  def after_destroy(picture_file)
    if File.exist?(picture_file.filepath)
      File.delete(picture_file.filepath)
    end
  end
end

عند الإعلان داخل صنف -كما في المثال أعلاه-، ستتلقى أساليب دالة الاستدعاء كائن النموذج كعامل، ونستطيع الآن استخدام صنف دالة الاستدعاء في النموذج:

class PictureFile < ApplicationRecord
  after_destroy PictureFileCallbacks.new
end

لاحظ أننا بحاجة إلى إنشاء كائن PictureFileCallbacks جديد لأننا أعلنا دالة الاستدعاء الخاصة بنا على أنها مثيل أسلوب(instance method) ،وستستفيد من هذا خاصة إذا استخدمت دوال الاستدعاء حالة الكائن المثيل، ومع ذلك، في الكثير من الأحيان، سيكون من المنطقي إعلان دوال الاستدعاء كأساليب الصنف:

 class PictureFileCallbacks
  def self.after_destroy(picture_file)
    if File.exist?(picture_file.filepath)
      File.delete(picture_file.filepath)
    end
  end
end

لن يكون من الضروري إنشاء كائن PictureFileCallbacks إذا أُعلن عن أسلوب دالة الاستدعاء بهذه الطريقة.

class PictureFile < ApplicationRecord
  after_destroy PictureFileCallbacks
end

يمكنك إعلان العدد الذي تريده من دوال الاستدعاء داخل أصناف دالة الاستدعاء.

10- عمليات دوال الاستدعاء

يوجد دالتي استدعاء إضافيتين تعمل عند الانتهاء من عملية قاعدة البيانات: after_commit و after_rollback، وهما مشابهين لـ after_save إلا أنهم لا يعملون حتى يُنفّذ التغيير في قاعدة البيانات أو يتم التراجع عنه، وهما مفيدان للغاية عندما تحتاج نماذج active record إلى التفاعل مع الأنظمة الخارجية والتي هي ليست جزء من عملية قاعدة البيانات.
على سبيل المثال، فكر في المثال السابق حيث احتاج نموذج PictureFile إلى حذف ملف بعد تدمير السجل، إذا أُصدر استثناء بعد استدعاء دالة الاستدعاء after_destroy و أُرجعت العملية، فسيحذف الملف وسيبقى النموذج في حالة غير متناسقة، على سبيل المثال، افترض أن picture_file_2 في الشيفرة البرمجية أدناه غير صحيح و أصدر أسلوب save! خطأََ:

PictureFile.transaction do
  picture_file_1.destroy
  picture_file_2.save!
End

يمكننا تجنب هذه المشكلة باستخدام دالة الاستدعاء after_commit:

class PictureFile < ApplicationRecord
  after_commit :delete_picture_file_from_disk, on: :destroy
 
  def delete_picture_file_from_disk
    if File.exist?(filepath)
      File.delete(filepath)
   end
  end
end

اقتباس

ملاحظة:
يُحدد الخيار :on عند تشغيل الاستدعاء، وإذا لم تضعه، ستشتغل دالة الاستدعاء عند كل عمل.

بما أنه من الشائع استخدام after_commit عند الإنشاء والتحديث والحذف، فتوجد أسماء مستعارة aliases لهذه العمليات:

• after_create_commit
• after_update_commit
• after_destroy_commit

class PictureFile < ApplicationRecord
  after_destroy_commit :delete_picture_file_from_disk
 
  def delete_picture_file_from_disk
    if File.exist?(filepath)
      File.delete(filepath)
    end
  end
end

اقتباس

تحذير:
تُستدعى دوال الاستدعاء after_commit وafter_rollback لجميع النماذج التي تنشئ، تُحدّث أو تُدمّر داخل كتلة العملية (transaction)، ومع ذلك، إذا أصدر استثناء داخل واحد من دوال الاستدعاء، فلن تنفذ بقية أساليب after_commit و after_rollback المتبقية، وعلى هذا النحو، إذا كانت شيفرة (code) دالة الاستدعاء تصدر استثناء، ستحتاج إلى التعامل معه داخل دالة الاستدعاء من أجل السماح بالعمل لبقية دوال الاستدعاء.

المصدر:
توثيقات Ruby on Rails

مقدمة

إنّ azk عبارة عن أداة خفيفة مفتوحة المصدر، تستطيع استخدامها لتنسيق بيئات التطبيقات. هل سبق أن كان لديك تطبيق يعمل على محطة العمل المحليّة الخاصة بك، ووجدت أنّ الإعدادات تختلف كليًا عندما تقوم بنشر التطبيق على مخدّم إنّتاج. تُقدّم هذه المقالة أداة تنسيق، تُدعى azk، والتي يتم استخدامها حاليًا من قبل هذه التطبيقات، وهي قابلة للاستخدام لأكثر من ذلك بكثير. عندما تقوم بنشر تطبيق جاهز للعمل مع azk، فإنّه يمكنك بسهولة إنّ تشغلّه محليًا أو في مخدّم إنّتاج. لا يجعل azk تشغيل التطبيق فقط سهلًا و سريعًا بل كل تبعياته أيضًا، بما فيها نظام التشغيل المطلوب، اللغات، أطر العمل، قواعد البيانات و التبعيات الأخرى (المهام الثقيلة، الطويلة، التكرارية، الأكثر عرضة للخطأ)، سواء كنت تعمل في بيئة محلية أو على مخدم.
إنّ غرض هذه المقالة، هو إظهار كيف يعمل azk كأداة تنسيق، باستخدام تطبيق Rails بسيط يُدعى Stringer كمثال. يهتم azk بالعديد من التفاصيل خلف الكواليس، لجعل عملية التنسيق أسهل. لهذا، تحوي هذه المقالة على العديد من الخطوات الاختيارية، التي ليست بضرورية لإعداد التطبيق المثال، ولكنها تشرح آلية عمل azk. سوف نقوم بتشغيل التطبيق من شفرة المصدر على جهاز حاسوب محلي، ثم نشره على مخدّم، و من ثم سنقوم ببعض التغييرات المحليّة، وبعدها نقوم بنشر هذه التغييرات، و من ثم سنقوم بعميلة الإرجاع. بعد إتمام هذه المقالة، سوق تحصل على فكرة جيدة حول كيفية عمل azk كأداة تنسيق سير عملية التطوير والنشر الخاصة بك.

كيف يعمل؟

بدايةً، يُنسق azk بيئة التطبيق على جهاز الحاسب المحلي الخاص بك. حالما يعمل التطبيق لديك محليًا، سيقوم azk أيضًا بتنسيق نشره إلى المخدّم Droplet الخاص بك. طالما يُشغل azk التطبيقات من شفرة المصدر، فإنّك تستطيع أن تعمل مع التطبيق محليًا (إذا كنت ترغب بذلك)، و من ثم تقوم بنشره أو استرجاعه مرة ثانية بدون أيّة خطوات إضافية خاصة. يعزل azk البيئات التي تستخدم الحاويات، ولهذا فمن الآمن تشغيل التطبيقات على جهاز الحاسب المحلي الخاص بك. يعمل azk مع كل من المشاريع الجديدة، تلك التي تبدأ منذ الصفر، أو مع الشيفرات الموجودة سابقًا.

استخدام azk مع تطبيقات مخصّصة

باستخدام القائمة الحالية من التطبيقات التي تم تشكيلها مسبقًا للعمل مع azk كأمثلة، و مع قليل من العمل الإضافي ستستطيع إعداد أي مشروع للعمل مع azk. للقيام بهذا أضف الملف Azkfile إلى مشروعك.
Azkfile عبارة عن ملف رئيسي manifest، يحتوي العناصر الضرورية لتشغيل التطبيق، و يقوم بتلخيص علاقاتها فيما بينها (نظام التشغيل، اللغات، قواعد البيانات، … ).
فوائد إضافة الملف Azkfile إلى مشروعك:

• استخدام azk لأتمته إعداد البيئة لمشروعك محليًا و عند النشر.
• يستطيع الأشخاص الأخرين، الذين يرغبون بنشر تطبيقك، القيام بهذا باستخدام azk.

المتطلبات الأساسية

للمتابعة مع هذه المقالة، فإنّك ستحتاج إلى جهاز حاسوب يقوم بتشغيل أية من أنظمة التشغيل التالية(64 - بت) للبيئة المحليّة الخاصة بك:

• Mac OS X 10.6 (Snow Leopard) أو أي إصدار لاحق.
• Ubuntu 12.04، 14.04 or 15.10
• Fedora 21 or 22

أيضاً ستحتاج إلى إنّ تكون قادر على تشكيل git commits.

• يحتاج جهاز حاسوبك إلى تثبيت Git. إنّظر إلى هذه السلسلة لاستخدام Git من أجل التعليمات الخاصة لأنظمة التشغيل Linux، أو قم بزيارة صفحة تحميل Git.
• تأكّد من قيامك بتشغيل الأوامر المقترحة :

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

وذلك قبل القيام بقراءة المقالة، انظر الروابط السابقة للحصول على التفاصيل حول Git. لاحظ أنّه لا يوجد ضرورة للحصول على مخدّم فعّال Droplet في هذا الدرس. سيقوم azk بتشكيل واحد باستخدام واجهة التطبيق DigitalOcean’s API. يُكلف نشر مخدم Droplet المال، ومن أجل هذا الدرس ستقوم بنشر مخدم Droplet، يحوي افتراضيًا فقط واحد جيجابايت.

مستخدمي Linux : تثبيت الـ Docker:
إذا كنت تستخدم نظام تشغيل ( Linux Ubuntu أو Fedora)، ستحتاج لتثبيت الـ 1.8.1 Docker أو أي اصدار لاحق، وذلك لاستخدامه كبرمجية حاويّة. إنّ تشغيل سكريبت تثبيت Docker، هي إحدى طرق تثبيته. (بشكل عام، كُن متأكد من فهمك ماذا يفعل السكريبت، وذلك قبل القيام بتشغيله):

 $ wget -nv https://get.docker.com/ -O- -t 2 -T 10 | bash

إذا كنت ترغب بتعلّم المزيد حول تثبيت Docker في نظام التشغيل Linux، تفحّص تعليمات التثبيت المتاحة في ملفات التوثيق الرسمية.
مستخدمي Mac OS X : تثبيت الـ VirtualBox:
ستحتاج إلى VirtualBox 4.3.6 أو أي اصدار لاحق، وذلك لاستخدامه كبرمجيّة حاويّة. لتثبيت VirtualBox، حمّل رزمة تثبيت Virtualbox المناسبة من صفحة التحميل الرسميّة.

الخطوة الأولى: تثبيت azk محليًا

سنقوم بتثبيت azk، باستخدام سكريبت تثبيت المشروع. تأكد من فهمك ماذا يفعل أي سكريبت، قبل تنفيذه في نظامك. إذا كان لديك للتو نسخة قديمة مثبتة من azk، فإنّك تستطيع استخدام سكريبت التثبيت لتحديث الـ azk. وإلا قُم بتفحص إرشادات تثبيت الحزم لنظم التشغيل المدعومة.
تثبيت azk على Linux:
إذا كنت تستخدم نظام التشغيل (Linux Ubuntu أوFedora)، قُم بتشغيل هذا الأمر في الوحدة الطرفية، وذلك لتثبيت azk باستخدام سكريبت المشروع. نحن ننصح بتدقيق أي سكريبت قبل تشغيله على نظامك:

$ wget -nv http://azk.io/install.sh -O- -t 2 -T 10 | bash

بعد إتمام التثبيت، قُم بتسجيل الخروج، ومن ثم تسجيل الدخول مرة أخرى، وذلك لجعل كل التعديلات فعّالة. يتجلى سبب تسجيل الخروج، في أنّه خلال عملية التثبيت، سيتم إضافة مستخدمك إلى مجموعة الـ docker. تُعد هذه الخطوة مطلوبة، وبذلك نستطيع استخدام الـ Docker بدون أن تكون المستخدم الأساسي (root). أي عليك الخروج من الجلسة الحالية، لتحصل على كل التعديلات المضافة. إذا كنت ترغب بتعلم المزيد حول مجموعة الـ Docker، فإنّك تستطيع تفحص التوثيق الرسمي لـ Docker.
تثبيت azk على Mac OS X:
قُم بتشغيل الأمر التالي في الوحدة الطرفية، وذلك لتثبيت azk باستخدام سكريبت المشروع. نحن ننصح بتدقيق أي سكريبت قبل تشغيله على نظامك:

$ curl -sSL http://www.azk.io/install.sh | bash

الخطوة الثانية: التحقق من تثبيت azk

حالما يصبح تثبيت azk كامل، قُم بتشغيل الأمر الذي في الأسفل، وذلك للتحقق من نجاح عملية التثبيت:

$ azk version

يتحقق هذا الأمر من نسخة الـ azk المثبّتة. إذا أعاد هذا الأمر رقم النسخة (على سبيل المثال azk 0.17.0 أو أي إصدار لاحق)، فالوضع جيد و تستطيع الانتقال إلى الخطوة التالية.
تهانينا لك على تثبيت azk في البيئة المحليّة الخاصة بك. إذا لم يكن الأمر كذلك، فاقرأ أدناه أحد أقسام تحرّي الأخطاء وإصلاحها للحصول على المساعدة.
استكشاف الأخطاء وإصلاحها في عملية تثبيت azk في Linux:
دعونا نتفحص نسخة الـ Docker المثبّتة، وذلك عن طريق تشغيل الأمر:

$ docker version

ستحتاج إلى الإصدار 1.8.1 أو أحدث.
على كل حال، إذا حصلت على رسالة خطأ، فهذا يعني لم تحصل حتى الآن على تثبيت Docker، تتبع إرشادات التثبيت الخاصة بنظام التشغيل في ملفات توثيق Docker.
بعد قيامك من التأكد من حصولك على النسخة المثبّتة المناسبة من Docker، قُم بتشغيل الأمر التالي كمستخدم sudo و ذلك للتأكد من أنّ مستخدمك في مجموعة docker:

$ id -Gn

إذا كانت قائمة المجموعات تتضمن docker، هذا يعني أنه تم إعداده بشكل صحيح. و إلا، إذا لم تحصل على الكلمة docker في قائمة المجموعات، قُم بتشغيل هذا الأمر لإضافة مستخدمك إلى المجموعة:

$ sudo usermod -aG docker $USER

ومن ثم قُم بتسجيل الخروج، و تسجل الدخول مرة أخرى. تحقق من الأمر id –Gn مرة أخرى للتأكد من أنّه يُعيد قائمة المجموعات مع كلمة docker بينهم. إذا كانت هذه الإرشادات غير كافية لجعل الـ Docker يعمل بالشكل المناسب (على سبيل المثال، لا تزال غير قادر على تشغيل أمر docker version بشكل صحيح)، يّرجى الرجوع إلى تعليمات تثبيت Docker.
استكشاف الأخطاء وإصلاحها في عملية تثبيت azk في Mac OS X:
تأكّد من تثبيت VirtualBox

$ which VBoxManage

إذا كان هذا يُعيد مسار ملف (مثل، usr/local/bin/VboxManage/)، فنستطيع المضي قُدمًا. و إلا، إذا كان يُعيد رسالة " not found "، هذا يعني ليس لديك تثبيت VirtualBox. في هذه الحالة، قُم بتحميل و تثبيت رزمة تثبيت VirtualBox من الموقع الرسمي لهم.

الخطوة الثالثة (اختيارية): التعلّم حول التطبيق التجريبي Stringer

لقد قُمنا باختيار Stringer كتطبيق تجريبي لهذه المقالة، وذلك لأنه تطبيق بسيط، وتم إعداده للعمل مع azk. وهو عبارة عن تطبيق Rails مع حالة استخدام محددة جيدًا: قارئ RSS أساسي.

المزيد حول Stringer

تُقدم بعض مواقع الأخبار أيضًا محتواها في صيغة تغذية RSS. هذه عبارة عن صيغة ملف XML قياسية، تُمكن الناشرين من نشر المعطيات بشكل اتوماتيكي. قارئ RSS هو عبارة عن برنامج مُستخدم للاشتراك، وتقديم محتوى الـ RSS. تُزيل عملية الاشتراك في تغذية RSS لموقع ما، حاجة المستخدمين للتفحص اليدوي للموقع للحصول على المحتوى الجديد. حيث يستطيع المستخدمين تشكيل قائمة بالتغذيات المُشترك فيها، وتخصيص محتواهم على قارئ RSS (عادةً على شكل قائمة مرتبة ترتيبًا زمنيًا)

الخطوة الرابعة (اختيارية): إعداد تطبيق مُخصّص لاستخدام azk

طالما أنّ التركيز الأساسي لهذه المقالة هو على إظهار كيفية عمل azk للتطبيقات، التي تملك للتو تفاصيل البيئة المنصوص عليها للعمل مع azk، فعلى المدى الطويل هذه الأداة، هي أكثر فائدة عندما يمكنك استخدامها لنشر أي تطبيق. لهذا، خُذ نظرة عن كيفية مقارنة هذه النسخة من Stringer مع النسخة الأساسية من Stringer في المستودع.
تملك نسخة azk فقط إضافتين اثنتين إلى نسخة Stringer الأصلية:

• ملف Azkfile، الذي يزّود بمعلومات البيئة لـ azk
• زر azk لتشغيل المشروع Run Project

يمكن تعلم المزيد حول جعل azk يعمل مع تطبيقات أخرى، وذلك عن طريق ملفات توثيق azk حول ملف Azkfile و زر تشغيل المشروع Run Project. تالياً، سوف نرى كيف يبدو التطبيق الصديق لـ azk في GitHub.

الخطوة الخامسة (اختيارية): استخدام زر تشغيل المشروع لـ azk على GitHub

إنّ جزء الممارسات الأفضل من azk من أجل مشاريع GitHub، هو التوضيح الجيد لكيفيّة عمل هذا المشروع مع azk. لهذا، بدلاً من إظهار فقط أمر الـ azk في وسط ملف readme للمشروع، فإنّ المشروع الذي يستخدم azk يستطيع استخدام زر تشغيل المشروع، وذلك للعزل البصري لأمر الـ azk. يستخدم Stringer هذا الزر. قُم بزيارة قسم التشغيل المحلي لنسخة azk المتشعبة من Stringer. أضغط زر تشغيل المشروع Run Project.

في أول مرة تضغط فيها زر تشغيل المشروع، سوف ترى شرح بسيط عن ماذا يجري. عندما تصبح جاهزا للمضي قُدماً، انقر على الزر OK، DISMISS في أسفل الشرح.

بعدها سيتم توجيهك إلى صفحة مع أمر azk لمشروع Stringer.

$ azk start -o run-project/stringer

يمكنك دائماً أنّ تنقر على إشارة ما هذا؟ على الزاوية العليا اليُمنى، وذلك لترى الشرح مرّة أخرى. في مركز الشاشة، يوجد صندوق أوامر مع ثلاث علامات تبويب: curl، wget، azk. طالما لدينا للتو مُثبت azk فتستطيع استخدام علامة التبويب azk. هذا هو الأمر، الذي سنستخدمه في الخطوة التالية للتشغيل الفعلي لـ Stringer.

الخطوة السادسة: تشغيل Stringer محليًا

في هذا القسم سنستخدم azk لتشغيل Stringer على محطّة العمل المحليّة. دعونا نتأكد أنّنا في المسار الرئيسي home على جهاز حاسوبنا المحلي (إذا قمت باستخدام مجلد تثبيت مختلف، تذكر فقط تغيير الأوامر إلى مسارك المختار):

$ cd ~

أمضي قُدمًا، و قم بتشغيل الأمر التالي على حاسوبك المحلي، وذلك لتشغيل Stringer:

$ azk start -o run-project/stringer

طالما هذه هي أول مره تقوم بها بتشغيل azk، سيطلب منك قبول بنود الخدمة. و يجب أنّ تظهر رسالة كالتالية:

? =========================================================================
 Thank you for using azk! Welcome!
 Before we start، we need to ask: do you accept our Terms of Use?
 http://docs.azk.io/en/terms-of-use
 =========================================================================
 (Y/n)

اضغط على Y إذا كنت موافق أو N إذا كنت غير موافق. و من ثم اضغط على ENTER لتأكيد جوابك. في حالة عدم موافقتك، فلن تتمكن من استخدام azk. و اخيراً، سيقوم azk أوتوماتيكيًا بتحميل الشفرة المصدر لـ Stringer، إضافة إلى أنّ الملف المسند Azkfile سيقوم بتشغيل هذا الشفرة في بيئة معزولة و آمنة في حاسوبك المحلي. ومن ثم سيتم سؤالك فيما إذا كنت ترغب ببداية تشغيل عميل الـ azk.

? The agent is not running، would you like to start it? (Y/n)

العميل هو عبارة عن مُركب azk، الذي يقوم بإعداد Docker (على نظام التشغيل Linux )، أو بإعداد الآلة الافتراضيّة VirtualBox (على نظام التشغيل Mac OS X). اضغط ENTER للجواب “Yes” (الخيار الافتراضي). في أول مرة تُشغل فيها العميل، سيقوم azk بتشغيل إعداداته. يقوم الإعداد بالعديد من الأشياء وراء الكواليس، بما في ذلك توليد الملف /etc/resolver/dev.azk.io، الذي يحوي إعدادات نظام أسماء النطاقات DNS، لتصميم العناوين التي تنتهي باللاحقة dev.azk.io. يستخدم azk هذه اللاحقة عند تشغيل التطبيقات لاستخدام العناوين القابلة للقراءة بدلاً من الاستخدام اليدوي للعناوين من الشكل http://localhost:PORT_NUMBER . أيضاً هذا يقوم بتجنب تعارض أرقام المنافذ بين التطبيقات المختلفة. بشكل أساسي يقوم هذا بنفس الشيء عند تحرير ملفك /etc/hosts لإعادة توجيه اسم نطاق محليًا.
إذا حصلت على رسالة من الشكل التالي:

? Enter the vm ip: (192.168.50.4)

فإنّك تستطيع إدخال أي عنون IP محلي، ترغب بتشغيل التطبيق عليه. يجب أن تكون الحالة الافتراضية مناسبة لجميع الحالات. للموافقة على هذا، فقط اضغط ENTER. لإتمام إعدادات عميل الـ azk، سيتم سؤالك عن كلمة المرور الخاصة بالمستخدم sudo (لمستخدمي نظام التشغيل Mac OS X، هي عبارة عن كلمة مرور المُشرف admin). الآن سيبدأ azk بالعمل. سوف ترى أنّ azk يُحمّل العناصر المُسردة في الملف Azkfile (على صيغة صور Docker ). من الممكن أن يستغرق تحميل هذه الصور أول مرة عدة دقائق (حوالي 10 دقائق أو أقل).
حالما يُكمل azk الإعداد، سيقوم مُتصفحك بشكل أتوماتيكي بتحميل شاشة البدء لـ Stringer على حاسوبك المحلي.

كما تستطيع إنّ ترى، أنّه يستخدم اسم نطاق محلي DNS، و هذا التطبيق مرئي على http://stringer.dev.azk.io. و تستطيع الوصول إلى التطبيق بشكل يدوي عبر الذهاب إلى http://stringer.dev.azk.io . إذا كنت ترغب بإعداد كلمة المرور و بداية التشغيل باستخدام التطبيق، فإنّك تستطيع فعل ذلك. نحن نرغب فقط برؤية أنّ azk يستطيع تشغيل Stringer محلياً. والآن طالما لديك Stringer يعمل على الحاسوب المحلي، فتستطيع نشره من جهاز الحاسوب لديك إلى المخدّم Droplet.

الخطوة السابعة: الحصول على الرمز DigitalOcean API Token

قبل أن نتمكن من نشر Droplet من azk، فإنّنا نحتاج إلى رمز API token. يُعطي هذا الرمز الإذن لـ azk لنشر مخدّم جديد على حسابك. في أول مرّة تقوم بها بتشغيل azk من هذه البيئة باستخدام هذا الرمز، سيتم نشر واحد جيجابايت مخدّم جديد Ubuntu 14.04 Droplet . و ستستخدم عمليات النشر اللاحقة من نفس البيئة المحليّة، نفس المخدّم المفرد Droplet. اتّبع الإرشادات من قسم المراجع المرتبطة بالمقالة حول كيفية تشكيل رمز الوصول الشخصي. و يجب أن يمتلك الرمز المُشكّل تصاريح الكتابة القراءة. قُم بنسخ المحارف الأربعة و الستين بالترميز الست عشري لرمزك، بشكل مشابه للتالي:

Example API Token

A17d6a72566200ad1a8f4e090209fe1841d77d7c85223f769e8c5de47475a726

سوف ترى هذا الرمز النصيّ فقط مرة واحدة، لذلك قُم بنسخه إلى مكان آمن. (تذكّر، إذا تم اختراق هذا الرمز، فإنّه يمكن استخدامه للدخول إلى حسابك، لذلك حافظ عليه خاصًا). من أجل الإرشادات أسفلا، تذكر استبدال الرمز المثال بالرمز الحقيقي الخاص بك.
اذهب إلى مجلد Stringer:

$ cd ~/stringer

احفظ رمز الوصول الشخصي في ملف ستدعوه env. للقيام بهذا، قُم بتشغيل أمر تشكيل ملف (لا تنسى استبدال الرمز):

$ echo "DEPLOY_API_TOKEN=a17d6a72566200ad1a8f4e090209fe1841d77d7c85223f769e8c5de47475a726" >> .env

يجب إنّ يبدو محتوى الملف env. بالشكل التالي:

DEPLOY_API_TOKEN=a17d6a72566200ad1a8f4e090209fe1841d77d7c85223f769e8c5de47475a726

الخطوة الثامنة (اختيارية): التعلم حول مفاتيح SSH

ليس عليك إنّ تقوم بأي شيء لإعداد مفتاح SSH من أجل azk، ولكن من المفيد معرفة الكيفية التي يستخدم فيها azk هذا المفتاح. يستخدم azk مفتاح SSH للوصول إلى المخدّم Droplet. إذا كان لديك للتو مفتاح SSH، فإنّ azk سيستخدمه. لرؤية فيما إذا كان لديك مفتاح SSH على جهاز الحاسوب لديك، شغّل:

$ ls ~/.ssh/*.pub

إذا قام بإرجاع رسالة “not found”، فهذا يعني إنّه ليس لديك أيّة مفاتيح SSH على جهاز الحاسوب. في هذه الحالة، سيولّد azk بشكل أتوماتيكي مفتاح SSH جديد، ليتم استخدامه حصريًا لنشر أي تطبيق جديد من جهاز الحاسوب لديك. سيقوم azk بتوليد مفتاحه في الذاكرة المحجوزة له، ولن يقوم بأيّة تعديلات على مسارك ~/.ssh.
إذا كنت ترغب بتفحص المفتاح العام المولّد، يمكنك تشغيل الأمر التالي بعد نشر التطبيق الأول:

$ azk deploy shell -c "cat /azk/deploy/.config/ssh/*.pub"

الخطوة التاسعة: النشر مع azk

بشكل افتراضي، سيولد azk مخدّم DigitalOcean Droplet واحد جيجابايت، يُشغّل النظام Ubuntu 14.04، وذلك من أجل نشر تطبيقك. إذا كنت ترغب بنشر Droplet بمواصفات مختلفة، فيمكنك تغيير الإعدادات في خصائص envs لنظام deploy في الملف Azkfile.js . من أجل الإرشادات الإضافية أشر إلى ملفات توثيق حول نشر azk .

أولاً، اذهب إلى مسار Stringer ( أو إلى مسار تطبيقك):

$ cd ~/stringer

ومن ثم، ابدأ عملية النشر، فقط قُم بتشغيل:

$ azk deploy

إنّ الأمر azk deploy، هو الأمر الذي ستقوم بتشغيله معظم الأوقات، عندما تستخدم azk لتنسيق تطبيقك. من الممكن أن تستغرق أول عملية نشر فترة معينة (حوالي عشر دقائق)، حتى يقوم azk بكل العمل. بشكل مخصص، على azk القيام بما يلي:

• تحميل عناصر الدعم ( صورة Docker للنشر)
• تشكيل و إعداد الـ Droplet
• رفع شفرة المصدر للتطبيق إلى المخدّم Droplet
• تشغيل التطبيق

بعدها ستستغرق كل عملية نشر جديده لهذا التطبيق من جهاز الحاسوب لديك مدة زمنية قليلة (حوالي 30 ثانية أو أقل)، هذا لان معظم الخطوات الطويلة جاهزة للتو. إذا كان مفتاحك SSH محمي بكلمة مرور، فسيكون مطلوباً وقت أكبر لعملية النشر. فقط قُم بكتابة كلمة المرور للمفتاح SSH، و أضغط زر ENTER في كل مرة تظهر رسالة كالتالية:

Output

Enter passphrase for ~/.ssh/id_rsa:

سيظهر خرج الوحدة الطرفية بعض الإجراءات المُتخذة على النظام البعيد، تنتهي برسالة النشر الناجحة App successfully deployed at http://your_server_ip.

قُم بزيارة الموقع http://your_server_ip لعرض التطبيق المُستضاف على الخادم الخاص بك.

من الآن، يُمكنك تغيير شفرة التطبيق على جهاز الحاسوب الخاص بك، و يمكنك اختباره محلياً، و يمكنك نشر التغييرات على المخدّم Droplet بواسطة الأمر azk deploy.

الخطوة العاشرة: تعديل Stringer

لتوضيح سهولة استخدام azk لنشر تطبيق، للتخصيص، أو للتحكم في النسخة، دعونا نقوم بعدد من التغييرات على صفحة الاشتراك Stringer، و من ثم نقوم بإعادة نشر التطبيق. تأكد من كونك على مسار Stringer:

$ cd ~/stringer

دعونا نقوم بتعديل الملف app/views/first_run/password.erb، الذي هو عبارة عن الصفحة الحاوية على النص لصفحة الاشتراك الأولى.
استخدم nano أو محرر النصوص المفضل لديك:

$ nano ~/stringer/app/views/first_run/password.erb

هنا نقوم بإضافة السطر الإضافي، الذي يقول "! It’s easy with azk ":

app/views/first_run/password.erb

<div class="setup" id="password-setup">
 <h1><%= t('first_run.password.title') %> <span class="orange"> <%= t('first_run.password.anti_social') %></span>.</h1>
 <h2><%= t('first_run.password.subtitle') %></h2>
 <h2>It's easy with azk!</h2>
 <hr />
 . . .
</div>

قُم بالحفظ و الخروج من محرر النصوص. إذا كنت تستخدم nano، اضغط CTRL+O للحفظ، و CTRL+X للخروج.
طالما إنّ Stringer مُعد افتراضياً للعمل في وضع الانتاج، لذلك فإنّ إعادة تحديث صفحة المتصفح ليس بكافٍ لتشغيل التغييرات. بل قُم بإعادة تشغيل التطبيق من azk:

$ azk restart stringer -o

يجب على علامة التبويب الجديدة للمتصفح أن تفتح النسخة الجديدة من Stringer. أسفل النص الافتراضي مباشرةً “There is only one user: you”، يجب الآن أن يكتب “!It’s easy with azk”.

الخطوة الحادية عشر: إعادة نشر Stringer

الآن، دعونا نُودع (commit) التغييرات داخل نسخة نظام التحكم، من أجل أن نستطيع نشرها.

$ git add app/views/first_run/password.erb
$ git commit .

سيظهر لك محرر نصوص (على الأرجح nano أو vim). أدخل رسالة إيداع commit، مثل It is easy with azk. سيتم استخدام هذه الرسالة commit لتسمية الإصدارات من تطبيقك داخل azk، لذلك اختر الرسالة التي من شأنها تحفيز ذاكرتك، إذا كنت بحاجة إلى الرجوع إليها في وقت لاحق. احفظ و أغلق رسالة الـ commit.
إذا حصلت على الخطأ :

 fatal: empty ident name (for <sammy@azk.(none)>) not allowed 

عندها قُم بتشغيل أوامر الإعدادات المقترحة من أجل Git لإعداد عنوان إيميل و اسم (المزيد من التفاصيل في قسم المتطلبات الأساسية).

لنشر تغييراتك و رفع تشغيل التطبيق على Droplet، قُم بتشغيل:

$ azk deploy

بعد الانتهاء من ذلك، قُم بالوصول إلى عنوان IP لـ Droplet من متصفحك (مثلاً http://your_server_ip) .عندها يجب أن ترى أيضاً هنا السطر الجديد !It’s easy with azk

سيقوم هذا النشر الجديد بتشكيل نسخة جديدة من التطبيق على Droplet. إنّ كل نسخ التطبيق مخزنة، لذلك يمكنك العودة إلى نسخة سابقة ومن ثم إلى الأمام مرّة أخرى.

الخطوة الثانية عشر: الرجوع إلى خطوة سابقة

للحصول على كل النسخ المتاحة من تطبيقنا على Droplet، شغّل الأمر التالي محليًا:

$ azk deploy versions

يجب إنّ تكون النتيجة بقائمة من الشكل:

Output

⇲ Retrieving deployed versions...

 ➜ v2   It is easy with azk
    v1   Merge branch 'master' of https://github.com/swanson/stringer

لإرجاع التطبيق إلى نسخة أقدم، فقط قوم بتشغيل:

$ azk deploy rollback v1

إنّ المعامل v1 عبارة عن رقم النسخة، الذي يظهر على خرج الأمر azk deploy versions. إذا قمت بتشغيل الأمر بدون هذا المعامل (مثلاً، . azk deploy rollback )، سيرجع عندها التطبيق إلى نسخة سابقة تماماً قبل النسخة الحالية. لتفحص إتمام عملية الرجوع، فقط قُم بتحديث علامة تبويب المتصفح، التي تظهر نسخة المخدم. الآن عليك إنّ ترى التطبيق بدون النص الذي قمنا بإدخاله، أي يجب أن ترى النسخة الأصليّة من التطبيق. وإذا كنت ترغب بالرجوع للأمام، يمكنك اختيار النسخة الأحدث:

$ azk deploy rollback v2

أتت التسمية لهذه النسخ من رسائل الـ git commit في الخطوة السابقة.

الخاتمة

في هذا الدليل التعليمي، لقد استخدمنا تطبيق Rails بسيط، لتوضيح كيف يقوم azk بأتمتة مهام إعداد بيئة تطبيقنا. يجعل هذا من السهل نشر التطبيق نفسه في عدة بيئات. إذا أعجبت بعملية النشر من azk، خُذ بعين الاعتبار استخدامه لمشروعك الخاص، أو إضافة الملف Azkfile إلى fork مشروع أخر مفتوح المصدر.
يدعم azk بالإضافة إلى عملية rollback و versions، غيرها من الأوامر الفرعيّة المساعدة، التي تسمح لنا بإنّجاز بعض الإجرائيات الإضافية (مثلاً، الوصول إلى Droplet’s shell عن طريق المفتاح SSH ).

ترجمة -وبتصرّف- للمقال How To Deploy a Rails App with azk لصاحبه Felipe Arenales

في الدرسين السابقين ألقينا نظرة عامة حول التحقيقات في Active Record وتعرّفنا على مساعدات التحقيقات وتعرّفنا أيضًا على الخيارات الشائعة وأنواع التحقيقات وسنتابع في هذا الدرس ما تبقى من هذا الدليل التعليمي .

6 أداء/تنفيذ تحقيقات مخصّصة Performing Custom Validations

عندما لا تكون التحقيقات المدمجة كافية لاحتياجاتك يمكنك كتابة محققاتك الخاصّة أو وسائل تحقيق كما تفضّل.

6.1 المحققات المخصّصة Custom Validators

المحققات المخصصة عبارة عن فئات تقتبس من ActiveModel::Validator. تلك الأصناف يجب أن تنفّذ وسيلة validate التي تأخذ سجل كـتعبير و تُؤدّي التحقيق عليه. يُستدعى المحقق الخاص باستخدام وسيلة validates_with.

class MyValidator < ActiveModel::Validator
  def validate(record)
    unless record.name.starts_with? 'X'
      record.errors[:name] << 'Need a name starting with X please!'
    end
  end
end

class Person
  include ActiveModel::Validations
  validates_with MyValidator
end

أسهل طريقة لإضافة محققات مخصّصة للتحقق من خصائص شخصيّة تكون ب ActiveModel::EachValidator مناسب. في هذه الحالة يجب أن ينفّذ المتحقق الخاص وسيلة validate_each ، التي تأخذ ثلاثة تعبيرات: سجل و خاصّية و قيمة. يتم إدارتهم مع ما يناسبهم: الخاصّية يتم التحقق منها ، و قيمة الخاصّية يتم تجاوزها.

class EmailValidator < ActiveModel::EachValidator
  def validate_each(record, attribute, value)
    unless value =~ /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i
      record.errors[attribute] << (options[:message] || "is not an email")
    end
  end
end

class Person < ApplicationRecord
  validates :email, presence: true, email: true
end

كما هو موضّح بالمثال يمكن دمج(ربط) محقّقات أساسيّة بمحقّقاتك الخاصّة.

6.2 الوسائل المخصّصة

يمكنك أيضًا إنشاء وسائل تؤكّد على حالة النموذج و تضيف رسائل إلى الـ errorscollection عندما يكونوا غير صالحين. يجب أن تسجّل بعد ذلك تلك الوسائل باستخدام فئة (validate (API ، مرورًا بالرموز الخاصة بأسماء وسائل التحقيق. يمكنك تمرير(إرسال) أكثر من رمز واحد لكل وسيلة لفئة و سيجري التحقيقات المخصصة في نفس الترتيب الذي سُجّلوا به. وسيلة ?valid سوف تؤكّد أن مجموعة الأخطاء فارغة، لذلك يجب أن تضيف تحقيقاتك المخصّصة أخطاء إليها عندما ترغب أن يفشل التحقيق.

class Invoice < ApplicationRecord
  validate :expiration_date_cannot_be_in_the_past,
    :discount_cannot_be_greater_than_total_value

  def expiration_date_cannot_be_in_the_past
    if expiration_date.present? && expiration_date < Date.today
      errors.add(:expiration_date, "can't be in the past")
    end
  end

  def discount_cannot_be_greater_than_total_value
    if discount > total_value
      errors.add(:discount, "can't be greater than total value")
    end
  end
end

كما هي مضبُوطة افتراضيّا ، سوف تعمل هذه التحقيقات كل مرّة تستدعي ?valid أو تحفظ الكائن. لكن من الممكن أيضًا التحكم في وقت عمل هذه التحقيقات بإعطاء خيار on: إلى وسيلة validate إما بـ create: أو update:

class Invoice < ApplicationRecord
  validate :active_customer, on: :create

  def active_customer
    errors.add(:customer_id, "is not active") unless customer.active?
  end
end

7 التعامل مع أخطاء التحقيق Working with Validation Errors

بالإضافة إلى وسائل ?valid و ?invalid التي تم شرحها مُسبقًا ، يدعم Rails عددًا من الوسائل للتعامل مع مجموعة الأخطاء و يحقق في صحّة الكائن.

7.1 الأخطاء Errors

ترجع فئة ActiveModel::Errors يحتوي على كل الأخطاء. كل مفتاح هو اسم الخاصّية و القيمة في مجموعة مصفوفة من المتسلسلات النصّية بالأخطاء.

class Person < ApplicationRecord
  validates :name, presence: true, length: { minimum: 3 }
end

person = Person.new
person.valid? # => false
person.errors.messages
 # => {:name=>["can't be blank", "is too short (minimum is 3 characters)"]}

person = Person.new(name: "John Doe")
person.valid? # => true
person.errors.messages # => {}

7.2 الأخطاء [ ] Errors

تستخدم errors عندما تريد أن تفحص رسالة الخطأ لخاصّية معيّنة. تقوم بالرد بمجموعة مصفوفة من المتسلسلات النصّية بكل رسائل الأخطاء لخاصّية مُعيّنة ، كل متسلسلة برسالة خطأ واحدة. لو لم يكن هناك أخطاء مرتبطة بالخاصّية ، تقوم بالرد بمصفوفة فارغة.

class Person < ApplicationRecord
  validates :name, presence: true, length: { minimum: 3 }
end

person = Person.new(name: "John Doe")
person.valid? # => true
person.errors[:name] # => []

person = Person.new(name: "JD")
person.valid? # => false
person.errors[:name] # => ["is too short (minimum is 3 characters)"]

person = Person.new
person.valid? # => false
person.errors[:name]
 # => ["can't be blank", "is too short (minimum is 3 characters)"]

7.3 إضافة الأخطاء errors.add

تجعلك وسيلة add أن تضيف رسالة خطأ مرتبطة بخاصّية مُعيّنة. تقوم بأخذ الخاصّية و رسالة الخطأ كتعابير. ترد وسيلة errors.full_messages (أو مكافئاتها errors.to_a ) برسالة الخطأ بشكل مفضّل للمستخدم ، و اسم الخاصّية مكبّرًا ومضافًا على بداية كل رسالة ، كما يظهر في الأمثلة بالأسفل.

class Person < ApplicationRecord
  def a_method_used_for_validation_purposes
    errors.add(:name, "cannot contain the characters !@#%*()_-+=")
  end
end

person = Person.create(name: "!@#")

person.errors[:name]
 # => ["cannot contain the characters !@#%*()_-+="]

person.errors.full_messages
 # => ["Name cannot contain the characters !@#%*()_-+="]

أن ترفق رسالة في بداية مصفوفة errors.messages لخاصّية ما ، مكافىء لأن تستخدم errors#add .

class Person < ApplicationRecord
  def a_method_used_for_validation_purposes
    errors.messages[:name] << "cannot contain the characters !@#%*()_-+="
  end
end

person = Person.create(name: "!@#")

person.errors[:name]
 # => ["cannot contain the characters !@#%*()_-+="]

person.errors.to_a
 # => ["Name cannot contain the characters !@#%*()_-+="]

7.4 تفاصيل الأخطاء errors.details

يمكنك تحديد نوع محقّق جدول تقطيع تفاصيل الخطأ المُعاد التقطيع باستخدام وسيلة errors.add.

class Person < ApplicationRecord
  def a_method_used_for_validation_purposes
    errors.add(:name, :invalid_characters)
  end
end

person = Person.create(name: "!@#")

person.errors.details[:name]
# => [{error: :invalid_characters}]

لكي تحسّن تفاصيل الأخطاء ، لتحتوي مجموعة الحروف غير المسموح بها على سبيل المثال ، يمكنك تمرير مفاتيح إضافيّة إلى errors.add.

class Person < ApplicationRecord
  def a_method_used_for_validation_purposes
    errors.add(:name, :invalid_characters, not_allowed: "!@#%*()_-+=")
  end
end

person = Person.create(name: "!@#")

person.errors.details[:name]
# => [{error: :invalid_characters, not_allowed: "!@#%*()_-+="}]

كل محقّقات Rails المدمجة تزيد جدول تقطيع التفاصيل بنوع محقّق متناظر.

7.5 قاعدة الأخطاء[ errors [ :base

يمكنك إضافة رسائلك أخطاء مرتبطة بحالة الكائن ككل بدلًا من كونها مرتبطة بخاصّية مُعيّنة. يمكنك أيضًا استخدام تلك الوسيلة عندما تريد أن تقول أن الكائن غير صالح للاستخدام ، بغض النظر عن قيم خصائصه. بما أن [errors[ :base مصفوفة ، يمكنك ببساطة إضافة متسلسلة نصّية إليها و سوف تُستَخدَم كَرسالة خطأ.

class Person < ApplicationRecord
  def a_method_used_for_validation_purposes
    errors[:base] << "This person is invalid because ..."
  end
end

7.6 محو الأخطاء errors.clear

تُستخدم وسيلة clear عندما تريد أن تمسح كل رسائل الخطأ في مجموعة الأخطاء errorscollection . بالطبع مناداة errors.clear لكائن غير صالح لن يجعله ساريًا أو صالحًا للاستخدام. مجموعة الأخطاء سوف تُفرّغ ، لكن المرة القادمة التي تستدعي فيها ?valid أو أي وسيلة تحاول أن تحفظ الكائن في قاعدة البيّانات ، سوف تعمل التحقيقات مجّددًا. لو فشل أيّ من التحقيقات سوف تُملأ مجموعة الأخطاء مجددًا.

class Person < ApplicationRecord
  validates :name, presence: true, length: { minimum: 3 }
end

person = Person.new
person.valid? # => false
person.errors[:name]
 # => ["can't be blank", "is too short (minimum is 3 characters)"]

person.errors.clear
person.errors.empty? # => true

person.save # => false

person.errors[:name]
# => ["can't be blank", "is too short (minimum is 3 characters)"]

7.7 حجم الأخطاء errors.size

ترد وسيلة size بالعدد الكلي لرسائل الأخطاء للكائن.

class Person < ApplicationRecord
  validates :name, presence: true, length: { minimum: 3 }
end

person = Person.new
person.valid? # => false
person.errors.size # => 2

person = Person.new(name: "Andrea", email: "andrea@example.com")
person.valid? # => true
person.errors.size # => 0

8 تقديم أخطاء التحقيق للعرض Displaying Validation Errors in Views

بمجرّد إنشائك نموذجًا و إضافة تحقيقات ، لو كان النموذج مصنوع بواسطة شكل المواقع ، من المحتمل أن تريد عرض رسالة عند فشَل أحد التحقيقات. لأن كل تطبيق يعالج هذا النوع من الأشياء بطريقة مختلفة ، لا يتضمّن Rails أي view helpers لتساعدك على توليد تلك الرسائل بصورة مباشرة. مع ذلك ، بسبب فرط الوسائل التي يعطيك إيّاها Rails لكي تتعامل مع التحقيقات بشكل عام، تكون العملية سهلة جدّا لإنشاء ما يخصّك منها. بالاضافة إلى ذلك ، عند إنتاج هيكل رئيسي مساعد ، سوف يضع Rails بعض ERB إلى _form.html.erb الذي تنتجه والذي يعرض قائمة بكل الأخطاء في النموذج. بافتراض أن لدينا نموذج تم حفظه في متغيّر باسم article@ ، سيبدو كالتالي:

<% if @article.errors.any? %>
  <div id="error_explanation">
    <h2><%= pluralize(@article.errors.count, "error") %> prohibited this article from being saved:</h2>

    <ul>
    <% @article.errors.full_messages.each do |msg| %>
      <li><%= msg %></li>
    <% end %>
    </ul>
  </div>
<% end %>

علاوةً على ذلك، إذا استخدمت تصميم Rails من المساعدين لتولّد تصميماتك(نماذجك)، عندما يحدث خطأ تحقيق في الحقل سوف تنتج <div> إضافي بالقرب من المدخل.

<div class="field_with_errors">
 <input id="article_title" name="article[title]" size="30" type="text" value="">
</div>`

يمكنك حين ذاك تشكيل ال div كما تريد. الهيكل الافتراضى الذي ينتجه Rails على سبيل المثال يضيف قاعدة ال CSS هذِهِ.

.field_with_errors {
  padding: 2px;
  background-color: red;
  display: table;
}

هذا يعني أنّ أي حقل به خطأ ينتهي به الحال بإطار أحمر بعرض 2 بكسل.

المصدر:
توثيقات Ruby on Rails.

في الدرسين السابقين ألقينا نظرة عامة حول التحقيقات في Active Record وتعرّفنا على مساعدات التحقيقات وسنتابع في هذا الدرس تعلم الخيارات الشائعة للتحقيقات وأنواع التحقيقات.

3 خيارات تحقيق شائعة common Validation Options

هذه خيارات تحقيق شائعة

3.1 اسمح بمجموعة خالية allow_nil

خيار allow_nil يتجاوز التحقيقات عندما تكون القيمة التي يجري عليها التحقيق nil.

class Coffee < ApplicationRecord
  validates :size, inclusion: { in: %w(small medium large),
    message: "%{value} is not a valid size" }, allow_nil: true
end

لكل الخيارات لمضمون الرسالة من فضلك اقرأ الفقرة (3.3 أمر الإرسال :message).

3.2 اسمح بالفراغ :allow_blank

خيار :allow_blank مماثل لخيار :allow_nil . الخيار سوف يتجاوز التحقيقات إذا كانت القيمة blank? (فراغ). مثل مجموعة أو سلسلة فارغة على سبيل المثال.

class Topic < ApplicationRecord
  validates :title, length: { is: 5 }, allow_blank: true
end

Topic.create(title: "").valid?  # => true
Topic.create(title: nil).valid? # => true

3.3 أمر الإرسال :message

كما رأيت مسبقًا ، خيار :message يسمح لك بتحديد الرسالة التي ستضاف إلى مجموعة الأخطاء عند فشل التحقيق. عندما لا يُستخدم هذا الخيار ، سيقوم Active Record باستخدام الوضع الافتراضي لرسائل الخطأ لكل مساعد تحقيق. يقبل خيار :message أي string أو  proc) و proc هو قالب من الكود الذي يتم إضافته أو قيده لمجموعة من المتغيّرات المحلّية ، و عندما يضاف يمكن أن يتم استدعاء هذا القالب في أكثر من سياق و يزال ويمكنه الوصول لتلك المتغيرات). قيمة رسالة سلسلة نصّية String :message يمكن –اختياريًا- أن تحتوي على أي أو كلّا من %{value} و %{attribute} و %{model} ، و التي سيتم تبديلها تلقائيّا عند فشل التحقيق. يتم هذا التغيير باستخدام I18n gem ، وماسك المكان يجب أن يتطابق تمامًا ، لا يُسمح بالمساحات. قيمة proc :message تُعطى تعبيرين ، الكائن الذي يتم التحقق منه ، و جدول تقطيع بأزواج key-value و هم :model و :attribute و :value .

class Person < ApplicationRecord
  # Hard-coded message
  validates :name, presence: { message: "must be given please" }

  # Message with dynamic attribute value. %{value} will be replaced with
  # the actual value of the attribute. %{attribute} and %{model} also
  # available.
  validates :age, numericality: { message: "%{value} seems wrong" }

  # Proc
  validates :username,
    uniqueness: {
      # object = person object being validated
      # data = { model: "Person", attribute: "Username", value: <username> }
      message: ->(object, data) do
        "Hey #{object.name}!, #{data[:value]} is taken already! Try again #{Time.zone.tomorrow}"
      end
    }

3.4 على :on

خيار :on يدعك تحدد متى ينبغي أن يجرى التحقيق. السلوك الافتراضي لكل مساعدين التحقيق المدمجين أن تجري عند الحفظ (عندما تكون تنشىء سجل جديد و عندما تقوم بتحديثه). إذا أردت تغير ذلك يمكنك استخدام on: :create لإجراء التحقيق فقط عند إنشاء سجل جديد ، أو on: :update لإجرائه عندما يتم تحديث السجل فقط.

class Person < ApplicationRecord
  # it will be possible to update email with a duplicated value
  validates :email, uniqueness: true, on: :create

  # it will be possible to create the record with a non-numerical age
  validates :age, numericality: true, on: :update

  # the default (validates on both create and update)
  validates :name, presence: true
end

يمكنك أيضًا استخدام on: لتحديد سياق مخصّص. يحتاج السياق المخصص إلى تنشيط بشكل صريح من خلال إرسال اسمه إلى valid? أو invalid? أو save.

class Person < ApplicationRecord
  validates :email, uniqueness: true, on: :account_setup
  validates :age, numericality: true, on: :account_setup
end

person = Person.new

.(person.valid? (:account_setup يستثنى كلا التحقيقين بدون حفظ النموذج. و (person.save(context: :account_setup) يتحقق من الشخص في سياق account_setup قبل الحفظ. على منشّطات صريحة ، يتم التحقق من النموذج بمحققات تابعة لهذا السياق فقط و محققات بدون سياق.

4 تحقيقات صارمة Strict Validations

يمكنك أيضًا اختيار محققات لتكون مشدّدة و تنشّط ActiveModel : :StrictValidationFailed عندما يكون الكائن غير ساري.

class Person < ApplicationRecord
  validates :name, presence: { strict: true }
end

Person.new.valid?  # => ActiveModel::StrictValidationFailed: Name can't be blank

يوجد أيضًا امكانية لعمل استثناء مخصّص على خيار :strict .

class Person < ApplicationRecord
  validates :token, presence: true, uniqueness: true, strict: TokenGenerationException
end

Person.new.valid?  # => TokenGenerationException: Token can't be blank

5 التحقيق المشروط conditional validation

في بعض الأوقات سيبدو من المنطقي أن يتم التحقق من كائن فقط عندما تُوفى معايير فلترة معيّنة. يمكنك عمل ذلك باستخدام خيارات :if و :unless ، التي يمكن أن تأخذ رمز ، سلسلة نصّية ، أو proc. يمكنك استخدام خيار :if عندما تريد أن تحدد متى ينبغى أن يجرى التحقيق. إذا كنت تريد أن تحدد متى لا ينبغي أن يجري التحقيق إذن استخدم خيار :unless

5.1 استخدام رمز مع إذا و إذا لم Using a Sympol with :if and :unless

يمكنك مصادقة خيارات :if و :unless مع رمز تناظر مع اسم الوسيلة التي سوف تُستدعى قبل حدوث التحقيق مباشرةً. هذا هو أكثر الخيارات الشائعة استخدامًا.

class Order < ApplicationRecord
  validates :card_number, presence: true, if: :paid_with_card?

  def paid_with_card?
    payment_type == "card"
  end
end

5.2 استخدام بروك مع إذا و إذا لم Using a Proc with :if and :unless

أخيرًا يمكن ربط :if و :unless مع كائن proc ، الذي سيتم استدعاؤه. استخدام Proc object يعطيك القدرة على كتابة شرط داخلي بدلًا من وسيلة منفصلة. هذا الخيار الأفضل لها فالاستخدام مع برامج السطر الواحد (ادخال نصّي إلى ال command-line الخاص بنظم تشغيل تقوم بوظائف ما بسطر واحد من الكود)

class Account < ApplicationRecord
  validates :password, confirmation: true,
    unless: Proc.new { |a| a.password.blank? }
end

5.3 تجميع التحقيقات الشرطيّة Grouping Conditional Validations

في بعض الأوقات يكون من المفيد أن يستخدم تحقيقات متعددة نفس الشرط. يمكن الوصول لذلك بسهولة من خلال with_options.

class User < ApplicationRecord
  with_options if: :is_admin? do |admin|
    admin.validates :password, length: { minimum: 10 }
    admin.validates :email, presence: true
  end
end

كل التحقيقات بداخل قالب with_options سيكون قد تجاوز تلقائيّا بالفعل شرط ?if: :is_admin .

5.4 ضم/دمج شروط التصديق Combining Validation Conditions

من ناحية أخرى ، عندما يحدد شروط متعددة إذا كان التحقيق ينبغي أن يجري أم لا ، يُمكن استخدام مصفوفة. إضافة إلى ذلك يمكنك تطبيق كلا من :if و :unless على نفس التحقيق.

class Computer < ApplicationRecord
  validates :mouse, presence: true,
                    if: ["market.retail?", :desktop?],
                    unless: Proc.new { |c| c.trackpad.present? }
end

يجري التحقيق فقط عندما يكون شروط :if محققة (قيمتها ture) ، و كل شروط :unless غير محقّقة.

سنتابع في الدرس القادم والأخير ما بقي من هذا الدليل التعليمي حول تحقيقات Active Record.

المصدر:
توثيقات Ruby on Rails.

في الدرس السابق ألقينا نظرة عامة حول التحقيقات في Active Record وسنتابع في هذا الدرس تعلم مساعدات التحقيقات

2 مساعدات التحقيقات validation helpers

يعرض Active Record العديد من مساعدات تحقيقات المعرفة مسبقًا التي يمكنك استخدامها مباشرة داخل تعريفات فئتك. تدعم تلك المساعدات قواعد تحقيقات شائعة. فى كل مرة يفشل تحقيق ، تضاف رسالة خطأ الى مجموعة أخطاء الكائن ، و ترتبط تلك الرسالة بالخاصية التي يتم التحقق منها. يقبل كل مساعد رقم اعتباطي من أسماء الخواص ، لذلك يمكنك إضافة نفس نوع التحقيق للعديد من الخواص بسطر كود واحد. جميعم يقبل خيارات on: و message: الاثنين يحددان متى يجب أن يتم اجراء التحقيق ، و أي رسالة يجب إضافتها إلى مجموعة الأخطاء فى حال فشلها ، على الترتيب. خيار ال on: يأخذ القيم create: (أنشىء) أو :update: (حدّث). هناك رسالة خطأ افتراضية لكل واحد من مساعدات التحقيق. تُستَخدم تلك الرسائل عندما لا يكون خيار message: محددًا. فلنأخذ نظرة على كل واحد من مساعدات التحقيق.

2.1 القبول acceptance

تتأكد هذه الطريقة اذا ما كان الـ checkbox فى واجهة تشغيل المستخدم معلّمًا عندما يتم إرسال أي نموذج. يتم استخدام هذه الطريقة غالبًا عندما يكون المستخدم بحاجة لقبول شروطك لتقديم الخدمة ، يؤكد على قراءة نص معيّن ، أو أي مفهوم مشابه.

class Person < ApplicationRecord
  validates :terms_of_service, acceptance: true
end

يجري هذا الفحص فقط إذا كانت شروط العمل ليست nil. رسالة الخطأ الافتراضية لهذا المساعد هي “must be acceptd” أي يجب أن تقبل. يمكن أيضًا تجاوز الرسالة المخصصة من خلال خيار الرسالة message.

class Person < ApplicationRecord
  validates :terms_of_service, acceptance: { message: 'must be abided' }
end

يمكن أيضًا أن تستقبل خيار accept: التي تحدد القيم المسموح بها لأن تعتبر مقبولة. إنها تعود كما هو افتراضي إلى [`1` , true] و يمكن أن تتغير بسهولة.

class Person < ApplicationRecord
  validates :terms_of_service, acceptance: { accept: 'yes' }
  validates :eula, acceptance: { accept: ['TRUE', 'accepted'] }
end

هذا التحقيق مخصص جدًا لتطبيقات المواقع و هذا “القبول” acceptance لا يحتاج إلى أن يسجّل في أي مكان بقاعدة البيانات. إذا لم يكن لديك مجال له ، سوف ينشىء المساعد خاصية افتراضية. إذا كان لا يوجد مجال في قاعدة بياناتك يجب أن يكون خيار القبول مفعّلًا أو يتضمن true وإلا لن يجري التحقيق.

2.2 validates.associated مرتبط بالتحقيق

يجب أن تستخدم هذا المساعد عندما يكون لنموذجك ارتباطات بنماذج أخرى و هم أيضًا بحاجة إلى أن يتم التحقق منهم. عندما تحاول حفظ كائن ، ?valid سيتم استدعائها لكل واحد من الكائنات المرتبطة.

class Library < ApplicationRecord
  has_many :books
  validates_associated :books
end

هذا التحقيق سوف يعمل مع كل أنواع الارتباطات.

اقتباس

تحذير: لا تستخدم validates_associated على نهايتي الـ associations. ستقوم كل واحدة باستدعاء الأخرى فى دائرة لا متناهية.

رسالة الخطأ الافتراضية لـ validates_associated هي “is invalid” أي غير صالح. لاحظ أن كل associated object لن يحتوي على مجموعة أخطائه ، الأخطاء لا تتصاعد إلى نموذج الاستدعاء.

2.3 التأكيد confirmation

يجب أن تستخدم هذا المساعد عندما يكون لديك حقول نصوص التي يجب أن تستقبل نفس المحتوى بالضبط. على سبيل المثال من الممكن أن تكون تريد التأكيد على عنوان بريد إلكتروني أو كلمة مرور. هذا التحقيق ينشىء خاصية افتراضية بنفس اسم الحقل الذي يجب أن يتم التأكيد عليه بـ”_confirmation” (تأكيد) مُلحق.

class Person < ApplicationRecord
  validates :email, confirmation: true
end

فى قالب العرض خاصتك يمكن أن تستخدم شيئًا مثل:

<%= text_field :person, :email %>
<%= text_field :person, :email_confirmation %>

هذا الفحص يجري فقط إذا كان email_confirmation ليس nil. لكي تطلب معلومات تأكد من إضافة presence check لخاصية التأكيد:

class Person < ApplicationRecord
  validates :email, confirmation: true
  validates :email_confirmation, presence: true
end

يوجد خيار case_sensitive الذي يمكنك استخدامه لتحدد إذا ما كان من قيود التأكيد أن يكون مستشعرًا لحالة الحروف أم لا (أي يفرق بين الحروف الـ capital و الـ small). والخيار الافتراضي له هو true.

class Person < ApplicationRecord
  validates :email, confirmation: { case_sensitive: false }
end

رسالة الخطأ الافتراضية لهذا المساعد هي “doesn’t match confirmation” أي لا يتوافق مع التأكيد.

2.4 استثناء exclusion

هذا المساعد يصدّق أن قيم الخواص ليست متضمّنة فى مجموعة معطاة. في الحقيقة ، تلك المجموعة يمكن أن تكون أي كائن غير قابل للعد.

class Account < ApplicationRecord
  validates :subdomain, exclusion: { in: %w(www us ca jp),
    message: "%{value} is reserved." }
end

يمتلك مساعد الاستثناء خيار in: الذي يستقبل مجموعة من القيم التي لن تقبل الخصائص المتحقق منها. خاصية in: لها اسم آخر متعارف عليه هو within: و الذي يمكن استخدامه لنفس الوظيفة. هذا المثال يستخدم خيار message: ليعرض كيف يمكن تضمين قيمة الخصّيصة. من أجل خيارات مفصّلة/كاملة لمتغير الرسالة. رسالة الخطأ الافتراضيّة هى “is reversed”

2.5 الشكل/التصميم format

هذا المساعد يتحقق من قيم الخواص باختبار اذا ما كانوا تطابق تعبير اعتيادي معطى ، الذي يتم تحديده باستخدام خيار with: .

class Product < ApplicationRecord
  validates :legacy_code, format: { with: /\A[a-zA-Z]+\z/,
    message: "only allows letters" }
end

بدلًا من ذلك يمكنك اختيار ألا تطابق الخواص المحددة expression معين باستخدام خيار without: . رسالة الخطأ الافتراضية هى “is invalid” .

2.6 التضمين inclusion

هذا المساعد يتحقق أن قيم الخواص متضمنة فى مجموعة معينة. هذه المجموعة يمكن أن تكون أي كائن غير معدود.

class Coffee < ApplicationRecord
  validates :size, inclusion: { in: %w(small medium large),
    message: "%{value} is not a valid size" }
end

مساعد التضمين inclusion helper لديه خيار in: الذي يستقبل مجموعة من القيم التي ستكون مقبولة. خيار in: لديه اسم آخر هو within: الذي يمكن استخدامه بدلًا منه لنفس الوظيفة. يستخدم المثال السابق خيار الـ message: ليبين كيف يمكن تضمين قيمة الخصّيصة. رسالة الخطأ الافتراضية لهذا المساعد هي “is not included in the list”.

2.7 الطول

هذا المساعد يتحقق من طول قيم الخصائص. إنه يدعم خيارات مختلفة حتى يتسنّى للمستخدم تحديد قيود الطول بطرق مختلفة.

class Person < ApplicationRecord
  validates :name, length: { minimum: 2 }
  validates :bio, length: { maximum: 500 }
  validates :password, length: { in: 6..20 }
  validates :registration_number, length: { is: 6 }
end

خيارات قيود الطول المتاحة هي:

• minimum: (أقل حد) الخاصية لا يمكن أن تكون أقل من الطول المحدد
• maximum:  (أقصى حد) الخاصية لا يمكن أن تكون أكثر من الطول المحدد.
• in: (أو within:) (في حدود) طول الخاصية يجب أن يكون متضمن في أبعاد معيّنة. قيمة هذا الخيار يجب أن يكون نطاق/مدى.
• is: (يساوي) طول الخاصية يجب أن يكون مساويًا للقيمة المعطاه.

رسالة الخطأ الافتراضيّة تعتمد على نوع تحقيق الطول المُجرى. يمكنك تخصيص هذه الرسائل باستخدام خيارات wrong_length: (طول خطأ) و too_long: (طويل جدًا) و too_short: (قصير جدًا) ، و  {count} كماسك للمكان للرقم المناظر لقيد الطول المُستخدم. يمكنك أيضًا استخدام خيار message: لتحدد رسالة الخطأ.

class Person < ApplicationRecord
  validates :bio, length: { maximum: 1000,
    too_long: "%{count} characters is the maximum allowed" }
end

لاحظ أن رسائل الأخطاء هي جمع (على سبيل المثال “قصير جدًا( الحد الأدنى هو {count} أحرف)”). لهذا السبب عندما يكون الحد الأدنى هو 1 يجب أن توفر رسالة مخصصة أو استخدم presence : true بدلًا من ذلك. عندما يمتلك in: أو within: حد أدنى 1 ينبغى عليك إما توفير رسالة خطأ مخصصة أو استدعاء presence طبقًا لأولوية الطول.

2.8 العددية numericality

هذا المساعد يتحقق أن خواصّك بها قيم عددية فقط. افتراضيّا ، سوف يقوم بالتحقق من وجود رقم صحيح integer أو عدد عشري floating point number. لتحدد السماح بالأرقام الصحيحة فقط اضبط only_integer: على true. إذا قمت بضبط only_integer: على true ، ستقوم باستخدام:

/\A[+-]?\d+\z/

عبارة اعتيادية للتحقق من قيمة الخصيصة. فيما عدا ذلك ستقوم بتحويل القيمة الى رقم باستخدام float.

class Player < ApplicationRecord
  validates :points, numericality: true
  validates :games_played, numericality: { only_integer: true }
end

بجانب only_integer: هذا المساعد يقبل أيضًا هذه الخيارات لإضافة قيود على القيم المقبولة:

• greater_than: تحديد القيمة الصُغرى للقيمة المُضافة
• greater_than_or_equal_to: تحديد القيمة الصُغرى مع إمكانية المساواة
• equal_to: القيمة المُضافة يجب أن تساوي
• less_than: تحديد القيمة الكُبرى للقيمة المضافة
• less_than_or_equal_to: تحديد القيمة الكُبرى مع إمكانية المساواة
• other_than: القيمة المُضافة يجب ألّا تساوي تلك القيمة
• Odd: القيمة المضافة يجب أن تكون فردية
• Even: القيمة المضافة يجب أن تكون زوجية

اقتباس

ملاحظة: الضبط الافتراضي للعددية لا يسمح بقيم nil. يمكنك استخدام خيار allow_nil: true للسماح بها.

رسالة الخطأ الافتراضية هى “is not a number” (ليس رقمًا).

2.9 وجود presence

هذا المساعد يتحقق أن الخصائص المحددة ليست فارغة. إنها تستخدم طريقة ?blank لتكتشف إذا كانت القيمة إما nil أو سلسلة فارغة blank string – و التي تكون سلسلة فارغة أو تتكون من مساحة.

class Person < ApplicationRecord
  validates :name, :login, :email, presence: true
end

إذا أردت أن تتأكد أن الارتباطات موجودة سوف تحتاج أن تختبر إذا ما كان الكائن نفسه موجودًا ، و ليس المفتاح الخارجي المستخدم لتنظيم الارتباط.

class LineItem < ApplicationRecord
  belongs_to :order
  validates :order, presence: true
end

يجب أن تحدد خيار inverse: للرابطة حتى تتحقق من السجلّات المرتبطة التي يجب أن تكون موجودة.

class Order < ApplicationRecord
  has_many :line_items, inverse_of: :order
end

إذا تحققت من وجود كائن من خلال علاقة has_one أو has_many سوف يفحص إذا ما كان الكائن ليس ?blank (فارغ) ولا marked_for_destruction (محدد للمحو)
بما أن ?false.blank صحيح ، ينبغى أن تستخدم أحد التحقيقات التالية إذا أردت التحقق من وجود حقل Boolean:

validates :boolean_field_name, inclusion: { in: [true, false] }
validates :boolean_field_name, exclusion: { in: [nil] }

باستخدام أحد هذه التحقيقات سوف تتأكد أن القيمة لن تكون nil ، مما سينتج عنه قيمة NULL فى أغلب الحالات.

2.10 الغياب absence

هذا المساعد يتحقق من أن الخصائص المحددة غائبة. إنها تستخدم وسيلة ?present لتكتشف إذا ما كانت القيمة ليست nil أو balnk string

class Person < ApplicationRecord
  validates :name, :login, :email, absence: true
end

إذا أردت التأكد أن التصادق غائب ، سوف تحتاج أن تختبر ما إذا كان الكائن نفسه غائبا أم المفتاح الخارجي المستخدم لتنظيم الارتباط.

 class LineItem < ApplicationRecord
  belongs_to :order
  validates :order, absence: true
end

حتى تتحقق من السجلات المتصادقة التي يلزم غيابها يجب أن تحدد خيار inverse_of: للمصادقة.

class Order < ApplicationRecord
  has_many :line_items, inverse_of: :order
end

إذا تحققت من غياب كائن من خلال علاقة has_one أو has_many ، سوف تفحص إذا ما كان الكائن ليس ?present أو ?marked_for_destruction مردودا كـ false. لو أردت التحقق من غياب حقل Boolean ينبغي أن تستخدم {[validates :field_name, exclusion: {in: [true, false .
رسالة الخطأ الافتراضية هى “must be blank”. أى يجب أن يكون فارغًا.

2.11 التفرّد/التميّز uniqueness

هذا المساعد يتحقق أن قيمة الخصيصة فريدة قبل حفظ الكائن مباشرة. إنها لا تنشىء قيد تفرّد uniqueness constraint في قاعدة البيانات ، لذلك من الممكن أن ينشىء قاعدتي بيانات مختلفتين سجلين مختلفين بنفس القيمة لعمود كنت تقصد جعله فريدًا. حتى تتجنّب ذلك يجب أن تنشىء مؤشّر متفرّد على هذا العمود في قاعدة بياناتك.

class Account < ApplicationRecord
  validates :email, uniqueness: true
end

التحقق يحدث بإجراء SQL query في جدول الوسائل ، بحثًا عن سجل موجود بنفس القيمة التي في الخاصية.
يوجد خيار scope: الذي يمكن استخدامه لتحديد خاصية أو أكثر تستخدم لتحديد فحص التفرّد.

class Holiday < ApplicationRecord
  validates :name, uniqueness: { scope: :year,
    message: "should happen once per year" }
end

إذا كنت تأمل فى إنشاء قيود في قاعدة البيانات لمنع أي انتهاك لتحقيق التفرّد باستخدام خيار scope: ، فعليك إنشاء فهرس فريد لكلا العمودين في قاعدة بياناتك. انظر the SQL manual لتفاصيل أكثر عن فهارس العواميد المتعددة أو the PostgresSQL manual لأمثلة على قيود فريدة تنطبق على مجموعة من الأعمدة. يوجد أيضًا خيار case_sensitive: الذي يمكنك استخدامه لتحديد ما إذا كان قيد التفرّد سيكون حساسًا لحالة الأحرف أم لا. الضبط الافتراضي للخيار يكون ساري/صحيح true.

class Person < ApplicationRecord
  validates :name, uniqueness: { case_sensitive: false }
end

اقتباس

تحذير: لاحظ أن بعض قواعد البيانات تكون مضبوطة أن تجري أبحاث case-sensitive على أي حال.

رسالة الخطأ الافتراضية هي “has already been taken”. أي تم أخده بالفعل.

2.12 يتحقق بـ validates_with

هذا المساعد ينقل السجل إلى فئة مختلفة من التصديق/التحقيق.

class GoodnessValidator < ActiveModel::Validator
  def validate(record)
    if record.first_name == "Evil"
      record.errors[:base] << "This person is evil"
    end
  end
end

class Person < ApplicationRecord
  validates_with GoodnessValidator
end

اقتباس

ملاحظة: الأخطاء المضافة إلى [ record.errors[ :base تتصل بحالة السجل ككل و ليس لخصّيصة معيّنة.

يأخذ مساعد validates_with فئة أو قائمة من الفئات لاستخدامها للتحقيق. لا يوجد رسالة افتراضية لرسائل الخطأ لـ validates_with. يجب عليك أن تضيف الأخطاء إلى مجموعة أخطاء السجل في فئة المحقق يدويًّا. لكي تنفّذ وسيلة التحقيق يجب أن تعرّف معامل السجل ، و الذي هو السجل الذي سيتم التحقق منه. على غرار باقي التحقيقات validates_with تأخذ خيارات if: و unless: و on: . إذا جرّبت أي خيار آخر سيقوم بإرسال تلك الخيارات إلى فئة المتحقق كخيارات متاحة.

class GoodnessValidator < ActiveModel::Validator
  def validate(record)
    if options[:fields].any?{|field| record.send(field) == "Evil" }
      record.errors[:base] << "This person is evil"
    end
  end
end

class Person < ApplicationRecord
  validates_with GoodnessValidator, fields: [:first_name, :last_name]
end

لاحظ أن المتحقق سوف يبدأ مرة واحدة فقط في دائرة عمر التطبيق ، و ليس لكل إجراء تحققي ؛ لذلك كن حذرًا عند استخدام متغيرات مقترحة/تجريبية بداخله. لو كان متحققك معقّد كفاية لدرجة أنك تريد متغيرات instance يمكنك استخدام plain old Ruby object بسهولة بدلاً من ذلك:

class Person < ApplicationRecord
  validate do |person|
    GoodnessValidator.new(person).validate
  end
end

class GoodnessValidator
  def initialize(person)
    @person = person
  end

  def validate
    if some_complex_condition_involving_ivars_and_private_methods?
      @person.errors[:base] << "This person is evil"
    end
  end

  # ...
End

2.13 تحقق من الكل validates_each

هذا المساعد يتحقق من الخصائص مقابل block. إنها لا تمتلك وظيفة تحقيق معينة ، يجب أن تنشىء واحدة باستخدام block و كل خاصية تمر إلى validates_each سوف تُختبر في مقابلها. في المثال التالي لا نريد الأسماء و أسماء العائلات أن تبدأ بحروف صغيرة.

class Person < ApplicationRecord
  validates_each :name, :surname do |record, attr, value|
    record.errors.add(attr, 'must start with upper case') if value =~ /\A[[:lower:]]/
  end
end

الـ block يستقبل السجل و اسم الخاصية و قيمة الخاصية. يمكنك فعل أي شىء ، مثل الكشف عن البيانات الصالحة داخل الـ block. إذا فشلت تحقيقاتك ينبغي عليك إضافة رسالة خطأ إلى النموذج، و من ثم جعله غير ساري.

سنتابع في الدروس القادمة بقية هذا الدليل التعليمي حول Active Record Validations.

المصدر:
توثيقات Ruby on Rails.

يوضح لك هذا الدليل كيفية التأكد من صحة وضع الكائنات Objects قبل دخولها فى قاعدة البيانات، باستخدام خاصية تصديقات Active Record.

1 نظرة عامة على التصديقات

مثال لعملية تصديق بسيطة :

class Person < ApplicationRecord
  validates :name, presence: true
end

Person.create(name: "John Doe").valid? # => true
Person.create(name: nil).valid? # => false

كما ترى في المثال ، يُعلِمُنا استخدام خاصية التصديق بأن ” Person ” غير ساري بدون خاصية الإسم. وكذلك Person الآخر لن يتم تثبيته في قاعدة البيانات.
قبل التعمق أكثر في التفاصيل، دعنا نتكلم أولاً عن كيفية ملائمة التصديقات في الصورة الكبيرة لتطبيقك.

1.1لماذا نستخدم التصديقات؟

تُستخدم التصديقات/التحقيقات للتأكد من أن البيانات الصالحة للاستخدام وحدها التي سيتم حفظها فى قاعدة البيانات. على سبيل المثال: يمكن أن يكون مهم لتطبيقك ضمان إدخال كل مستخدم لعنوان بريد إلكتروني و عنوان بريدي صالح للاستخدام. التحقيقات التي تكون على المستوى النموذجي Model-level Validations هى الطريقة الأمثل لضمان حفظ البيانات السارية وحدها بقاعدة بياناتك. إنها قابلة للتشغيل المتبادل على قواعد البيانات ، حيث لا يمكن للمستخدم تجاوزها أو التحايل عليها من أي مستخدم، و مناسبة للاختبار و التعامل المستمر. Rails تجعلها سهلة الاستخدام، توفّر مساعد مدمج للاستخدامات الشائعة، و تسمح لك بصناعة طرق التحقق الخاصة بك أيضًا.

هناك العديد من الطرق للتحقق من صحة البيانات قبل حفظها فى قاعدة البيانات، بما فى ذلك بعض القيود المرتبطة أساسًا بقاعدة البيانات، تصديقات من جانب العميل client-side validations، و تصديقات على مستوى التحكم controller-level validation.

إليك ملخّص السلبيّات و الإيجابيّات:

• قيود قواعد البيّانات و/أو الإجراءات المخزّنة تجعل آليّات التحقيق معتمدة على قاعدة البيّانات، و يمكن أن تجعل الإختبار و الصيانة أكثر صعوبة. مع ذلك، لو كانت قاعدة البيانات الخاصة بك تستخدم بواسطة تطبيقات أخرى، فقد تكون فكرة جيدة أن تستخدم بعض القيود على مستوى قاعدة البيّانات. بالإضافة إلى ذلك، التصديقات التي تكون على مستوى قاعدة البيانات يمكن أن تتعامل بأمان مع بعض الأشياء التي يصعب تطبيقها بالطرق الأخرى (مثل التميز/التفرّد فى الجداول المستخدمة بكثرة).
• يمكن للتحقيقات التي تكون من جهة العميل مفيدة، لكنها بشكل عام لا يُعتَمد عليها إذا تم استخدامها وحدها. إذا تم تنفيذها باستخدام JavaScript يمكن تجاوزها إذا كانت JavaScript غير مفعّلة في متصفّح المستخدم. مع ذلك، اذا تم دمجها مع تقنيّات أخرى يمكن أن تكون هذه التحقيقات طريقة مناسبة لتوفير ردود أفعال لمستخدمي موقعك.
• Controller-level validations يمكن أن تكون مغرية للاستعمال، لكن في الغالب تصبح غير عمليّة و صعبة في الاختبار و الصيانة. من الجيد أن تجعل متحكماتك صغيرة، حيث ستجعل تطبيقك محبب للاستخدام على المدى الطويل.
  قم بالإختيار مما سبق فى بعض الحالات التي تراها مُناسبة. لكن رأى فريق Rails أن model-level validations هي الأكثر تناسبًا لجميع الظروف.

1.2لماذا يحدث التحقيق؟

هناك نوعان من كائنات Active Record: تلك التي تتوافق مع صف بداخل قاعدة بياناتك، و تلك التي لا تتوافق. عندما تنشىء كائن جديد – باستخدام طريقة new على سبيل المثال - هذا الكائن لا ينتمي لقاعدة البيانات حتّى اللحظة. ما إن تقوم باستدعاء save لهذا الكائن سيتم حفظه في الجدول المناسب بقاعدة البيانات. يستخدم Active Record طريقة ?new_record لتحديد إذا ما كان الكائن موجود في قاعدة البيانات أم لا. فكّر في فئة Active Record التالية:

class Person < ApplicationRecord
end

يمكننا ملاحظة أنها تعمل بالنظر إلى ناتج rails console:

$ bin/rails console
>> p = Person.new(name: "John Doe")
=> #<Person id: nil, name: "John Doe", created_at: nil, updated_at: nil>
>> p.new_record?
=> true
>> p.save
=> true
>> p.new_record?
=> false

إن إنشاء و حفظ سجل جديد سوف يرسل عمليّة SQL INSERT إلى قاعدة البيانات. تحديث سجل موجود سوف يرسل عملية SQL UPDATE بدلًا من ذلك. التحقيقات تُجرى عادةً قبل إرسال هذه الأوامر إلى قاعدة البيانات. في حين فشل أي تحقيق سيتم تحديد الكائن “غير صالح” و لن ينفّذ Active Record عمليات الإدخال أو التحديث. يتجنّب هذا تخزين كائنات غير سارية في قاعدة البيانات. يمكنك أيضًا اختيار إجراء تحقيقات معينة عند إنشاء وحفظ أو تحديث كائن.

اقتباس

تحذير: هناك طرق كثيرة لتغيير حالة الكائن في قاعدة البيانات. سوف تنشّط بعض الطرق التحقيقات، لكن بعضها لن يفعل ذلك. هذا يعني أنه من الممكن أن يتم حفظ كائن بقاعدة البيانات في حالة غير صالحة إذا لم تكن حذرًا.

الطرق التالية تُشغل التحقيقات و سوف تحفظ الكائنات في قاعدة البيانات فقط إذا كانت صالحة للاستخدام:

• create
• !create
• save
• !save
• update
• !update

الأوامر التى تنتهي بـ bang versions (مثل !save على سبيل المثال) تقوم بعمل استثناء فى حالة عدم صحة السجل. الآخرون لا يفعلون ذلك. Save و update يُخرجوا false خطأً ، و create تُعيد نفس الكائن.

1.3 تخطّى التحقيقات

الدوال التالية تتخطى التحقيقات و تحفظ الكائن فى قاعدة البيانات بغض النظر عن صحّته. لذلك يجب استخدامها بحذر.

• !decrement
• decrement_counter
• !increment
• increment_counter
• !toggle
• touch
• update_all
• update_attribute
• update_column
• update_columns
• update_counters

لاحظ أن save لديها القدرة على تخطي التحقيقات إذا تم إلحاقها بالأمر validate: false. هذه الطريقة أيضًا يجب استخدامها بحرص.

• (save(validate: false

1.4 ?Valid و ?invalid  صالح؟ و غيرصالح؟

قبل حفظ كائن في Active Record، يجري Rails تحقيقاتك. لو كانت هذه التحقيقات تخرج أخطاء، لا يقوم Rails بحفظ الكائن. يمكنك أيضًا إجراء هذه التحقيقات بنفسك. ?Valid ينشّط تحقيقاتك و يرد بـ true (صحيح) إذا لم يكن هناك أخطاء. و false (خطأ) فيما عدا ذلك. كما رأيت بالأعلى:

class Person < ApplicationRecord
  validates :name, presence: true
end

Person.create(name: "John Doe").valid? # => true
Person.create(name: nil).valid? # => false

بعد إجراء Active Record لتحقيقاتك، يمكن الوصول لأي خطأ من خلال وسيلة errors.messages التي ترد بمجموعة من الأخطاء. كما هي معرّفة، الكائن صالح للاستخدام إذا كان تجمع الأخطاء هذا فارغًا بعد إجراء التحقيقات. لاحظ أن الكائن الممثل بـ new لن يبلغ عن أخطاء حتى لو كان غير صالح تقنيًّا، لأن التحقيقات تُجرى تلقائيّا عندما يتم حفظ الكائن، كما هوالحال مع دوال create و save.

class Person < ApplicationRecord
  validates :name, presence: true
end

>> p = Person.new
# => #<Person id: nil, name: nil>
>> p.errors.messages
# => {}

>> p.valid?
# => false
>> p.errors.messages
# => {name:["can't be blank"]}

>> p = Person.create
# => #<Person id: nil, name: nil>
>> p.errors.messages
# => {name:["can't be blank"]}

>> p.save
# => false

>> p.save!
# => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank

>> Person.create!
# => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank

?Invalid هي ببساطة عكس ?valid. تقوم بإجراء التحقيقات و ترد بـ true إذا وُجِدَ أي خطأ ، و false إذا لم تتواجد أيّة أخطاء.

1.5  [ ] errors الأخطاء

لكي تتأكد ما اذا كانت خاصّية معينة لكائن سارية أم لا يمكنك استخدام [ errors [ :attribute. تقوم بالرد بمصفوفة array بكل الأخطاء للخاصيّة. إذا لم يكن هناك أخطاء للخاصية المحددة يتم الرد بمصفوفة فارغة. تكون تلك الطريقة مفيدة بعدما تُجرى التحقيقات فقط، لأنها تقوم بفحص مجموعات الأخطاء فقط ولا تنشّط التحقيقات بنفسها. إنها تختلف عن طريقة ?ActiveRecord::Base#invalid المشروحة بالأعلى، لأنها لا تؤكّد صحّة الكائن ككل. إنها تقوم فقط بفحص إذا وُجد أخطاء بخاصيّة واحدة بالكائن.

class Person < ApplicationRecord
  validates :name, presence: true
end

>> Person.new.errors[:name].any? # => false
>> Person.create.errors[:name].any? # => true

1.6 errors.details تفاصيل الأخطاء

لكي تكشف أي تحقيقات فشلت في خاصية معيّنة يمكنك استخدام [ errors.details [ :attribute . تقوم بالرد بمصفوفة من الـ hashes مع مفتاح  error: للحصول على رمز المصادقة:

class Person < ApplicationRecord
  validates :name, presence: true
end

>> person = Person.new
>> person.valid?
>> person.errors.details[:name] # => [{error: :blank}]

المصدر:
توثيقات Ruby on Rails.

في الدروس السابقة ألقينا نظرة عامة على تهجير Active Record وكيفية إنشائه كما وتعلمنا أوامر التهجير وسنتابع في هذا الدرس ما بقي من هذه السلسلة التعليمية حول تهجير Active Record.

4 تشغيل التهجير Running Migration

Rails توفر مجموعة من مهام bin/rails لتشغيل مجموعة التهجيرات التي تريدها. إن أول مهام التهجير bin/rails التي ستستعملها سيكون غالبًا rails db:migrate. و هذا هو أبسط صور التهجير حيث يقوم بتشغيل دوال change و up لكل التهجيرات التي لم تقم بتشغيلها بعد. و سيقوم بالإغلاق إن لم يُكن لديك تهجيرات من هذا النوع. عدا ذلك سيقوم بتشغيل التهجيرات بالترتيب طبقًا لتوقيته. لاحظ أن تشغيل أمر db:migrate سيقوم بتشغيل الأمر db:schema:dump و هذا سوف يقوم بتحديث ملف db/schema.rb ليوافق تركيب قاعدة بياناتك. إذا قُمت بتحديد نُسخة version معينة، فإن Active Record سيقوم بعمل التهجيرات اللازمة (باستخدام دوال change و up و down) حتى يصل للنسخة المرغوبة. يُعبر عن النسخة باستخدام أرقام توضع في إسم ملف التهجير، فإذا أردت أن تقوم بالتهجير لنُسخة 20080906120000 قُم بتشغيل:

$ bin/rails db:migrate VERSION=20080906120000

إذا كانت النُسخة المرغوبة تحمل رقم أعلى من الرقم السابق فإن التهجير سيقوم بتشغيل دوال change أو up. و يقوم بعمل التهجيرات حتى يصل إلى رقم النُسخة المرغوبة. أما إذا كانت النسخة المرغوبة تحمل رقمًا أعلى فإن التهجير سيقوم بتشغيل دالة down حتى تصل إلى رقم النُسخة، لكنه لن يقوم بعمل تهجير لها(لأن ذلك سيؤدي إلى نُسخة أقل من المرغوبة).

4.1 العودة للوراء باستخدام rollback

سيتحتم عليك أحيانًا العودة بالتهجير للوراء (لاحظ الفرق بينه و بين العكس). مثال: إذا أردت أن تقوم بتصحيح خطأ قُمت به، فبدلًا من تتبع رقم النُسخة المرتبطة بذلك التهجير، يُمكنك تشغيل هذا الكود:

$ bin/rails db:rollback

إن أمر rollback سيقوم بعكس دالة change أو تشغيل دالة down. أما إذا أردت أن تعود لأكثر من تهجير يُمكنك تحديد عدد المرات التي ستعمل فيها الدالة rollback عن طريق STEP. مثال:

$ bin/rails db:rollback STEP=3

هذا سوف يعكس 3 تهجيرات. إن أمر db:migrate:redo يُعتبر إختصار لأمر rollback و لكنه سيعود بك لنقطة البداية مُجددًا. و يُمكنك تعيين عدد الخطوات به أيضًا باستخدام STEP، مثال:

$ bin/rails db:migrate:redo STEP=3

إن دالة db:migrate يُمكنها أي شيئ تقوم به أوامر bin/rails ولكنهم أكثر مُلائمة عندما لا تحتاج لتحديد النُسخة التي تعمل عليها بدقة.

4.2 تهيئة قاعدة البيانات Setup Database

أمر rails db:setup سيقوم بصنع قاعدة البيانات و تحميل الإسكيما و تزويدها ببياناتها الأولية.

4.3 إعادة تهيئة قاعدة البيانات Resetting Database

لإعادة التهيئة استخدم أمر rails db:reset ثم قُم باستعمال أمر التهيئة من جديد. و هذان الأمران يُمكن استبدالهما بدالة rails db:drop db:setup

اقتباس

لاحظ أن هذا الأمر مُختلف عن تشغيل التهجيرات كُلها مرة واحدة. حيث سيقوم باستعمال الملف الحالي سواء كان db/schema.rb أو db/structre.sql أما إذا كان التهجير لا يُمكن تطبيق دالة العودة rollback عليه، فلن يُمكنك إستخدام أمر rails db:reset

4.4 تشغيل تهجيرات محددة Running Specific Migrations

إذا كُنت تريد إجراء عملية تهجير محددة سواء للأمام up أو للخلف down. فيُمكنك إستخدام أمر db:migrate:up أو db:migrate:down و لكن سيتوجب عليك تحديد تعيين رقم نُسخة التهجير الذي ترغب بعمله، مثال:

$ bin/rails db:migrate:up VERSION=20080906120000

في المثال السابق سيقوم Active Record بالتأكد من وجود هذا التهجير مُسبقًا أم لا. فإن لم يكن موجودًا من قبل فسيقوم بتشغيل دالة change أو دالة up. أما إذا كان موجودًا بالفعل فلن يقوم بشيء.

4.5 تشغيل التهجير في بيئات عمل مختلفة different environments

تلقائيًا يتم تشغيل bin/rails db:migrate في بيئة development. ويُمكنك استعمال هذا الأمر RAILS_ENV لتحديد بيئة العمل التي ترغب بعمل التهجير عليها، في الكود التالي سنقوم بعمل التهجيرات على بيئة test:

$ bin/rails db:migrate RAILS_ENV=test

4.6 تغيير ناتج (خارج – Output) التهجير

إن التهجير تلقائيًا يقوم بإخبارك بالمهام التي يفعلها و الوقت الذي قد يأخذه، فإذا قُمت باستخدام تهجير لصنع جدول أو إضافة قاموس، فإن الناتج سيكون هكذا:

==  CreateProducts: migrating =================================================
-- create_table(:products)
   -> 0.0028s
==  CreateProducts: migrated (0.0028s) ========================================

و هُناك العديد من الدوال المتوفرة داخل ملفات التهجير تساعد بمعرفة هذا الأمر:

على سبيل المثال، فإن هذا التهجير:

class CreateProducts < ActiveRecord::Migration[5.0]
  def change
    suppress_messages do
      create_table :products do |t|
        t.string :name
        t.text :description
        t.timestamps
      end
    end

    say "Created a table"

    suppress_messages {add_index :products, :name}
    say "and an index!", true

    say_with_time 'Waiting for a while' do
      sleep 10
      250
    end
  end
end

سوف يُنتج هذه المُخرجات

==  CreateProducts: migrating =================================================
-- Created a table
   -> and an index!
-- Waiting for a while
   -> 10.0013s
   -> 250 rows
==  CreateProducts: migrated (10.0054s) =======================================

أما إذا أردت من Active Record ألا يُخرج أي شيئ فيُمكنك استخدام أمر rails db:migrate VERBOSE=false

5 تغيير التهجيرات الموجودة مُسبقًا

إذا قُمت بارتكاب خطأ ما أثناء كتابتك للتهجير، و قُمت بتشغيل التهجير. فلا يُمكنك تعديل التهجير ثًم تشغيله من جديد. لأن Rails لن تفعل شيئًا عند كتابة الأمر rails eb:migrate لأنك بالفعل قُمت بتشغيله من قبل. لذلك عليك استخدام أمر العودة rollback بكتابة bin/rails db:rollback ثُم تعديل التهجير ثُم تشغيله من جديد. بوجه عام، تعديل التهجيرات السابقة ليس أمرًا جيدًا، لأنه سيتسبب لك بالكثير من العمل، أنت و من يعملون معك على قاعدة البيانات. خصيصًا إن تم تشغيل هذا التهجير على أجهزة السيرفرات بالفعل. فبدلًا من عمل ذلك يُمكنك كتابة تهجير جديد وظيفته هي تغيير الأخطاء أو عمل التعديلات اللازمة. فإن تعديل تهجير مكتوب حديثًا أسهل من تعديل تهجير تم تشغيله على الأجهزة فعلًا. يُمكنك إستخدام أمر العاكس revert الذي تحدثنا عنه هُنا مُسبقًا.

6 إهمال الإسكيما Schema Dumping

6.1 ماهي ملفات الإسكيما؟

إن التهجيرات، ليست هي المُتحكمة بالإسكيما الخاصة بقاعدة بياناتك. إن هذا الأمر (التحكم) يعود إلى ملفات db/schema.rb أو ملف SQL. و تلك الملفات تولد من Active Record عن طريق مُعاينة قاعدة البيانات. وإن تلك الملفات ليست مُصممة ليتم التعديل عليها، بل هي تُظهر و تُمثل حالة قاعدة البيانات. ليس هُناك حاجة لعمل جزئية جديدة بتطبيقٍ ما عن طريق إعادة تشغيل جميع التهجيرات بالتطبيق. فإنه من الأسهل و الأسرع إضافة وصف تلك الجزئية للإسكيما الحالية لقاعدة البيانات. هكذا تكون قاعدة البيانات الإختبارية على سبيل المثال، بحيث يتم إهمال الملفات الحالية لقاعدة البيانات (ملف db/schema.rb و db/structre.sql) و يتم تحميلها إلى قاعدة البيانات الإختبارية test database. إن ملفات الإسكيما مُفيدة أيضًا إذا أردت أن تلقي نظرة سريعة إلى الخصائص التي تحملها كائنات Active Record. حيث أن هذه المعلومات لا توجد في كود نموذج قاعدة البيانات و أحيانًا تكون مُنتشرة بين العديد من التهجيرات، لكن المعلومات تكون جميعها موجود في ملفات الإسكيما بشكل مُنظم.

6.2 أنواع إهمال الإسكيما schema dumps

هُناك طريقتين أساسيتين لهجر/إهمال إسكيما ما. هذا يكون موجودًا داخل ملف config/application.rb عن طريق إعداد config.active_record.schema_format، و من المُمكن أن يكون ملف روبي ruby: أو  sql:
إذا كان من نوع روبي ruby: فإنه سيبدو مثل تهجير كبير، و ستجده داخل db/schema.rb، مثال:

ActiveRecord::Schema.define(version: 20080906171750) do
  create_table "authors", force: true do |t|
    t.string   "name"
    t.datetime "created_at"
    t.datetime "updated_at"
  end

  create_table "products", force: true do |t|
    t.string   "name"
    t.text     "description"
    t.datetime "created_at"
    t.datetime "updated_at"
    t.string   "part_number"
  end
end

في كثير من الحالات، يتم صُنع هذه الملفات عن طريق مُعاينة قاعدة البيانات و تركيبها باستعمال الدوال المُستخدمة بصُنعها مثل create_table و add-Index و غيرهم. و لأن هذا أمر يكون مُستقل بقاعدة البيانات، فيُمكن استخدامها على أي قاعدة بيانات يدعمها Active Record. ومن فوائد هذا الأمر، أنه يُمكنك توزيع بيانات تطبيق ما على العديد من قواعد البيانات. من سلبيات ملف الإسكيما db/schema.rb أنه لا يُمكنك التعبير عن جميع مُكونات قاعدة البيانات مثل: المُشغلات/مُنشطات triggers و نقاط التحقق check constraints. بينما في التهجير يُمكنك الإستعانة بسطور  SQL. و الإسكيما لا يُمكنها أن تحتوي على تلك السطور. لذلك إن إحتوت قاعدتك بيانات على مثل هذه الخصائص، فيجب عليك تحويل صيغة ملف الإسكيما إلى sql:.
بدلًا من إهمال استعمال إسكيما Active Record، فإنه يُمكنك إهمال تركيب/تخطيط قاعدة البيانات بإستخدام أدوات مُعينة مثل (أمر rails db:structre:dump ) في ملف db/structre.sql. على سبيل المثال: في قواعد بيانات من نوع PostgreSQL يُمكنك إستخدام pg_dump. أما في قواعد بيانات MySQL و MariaDB فإن الملف سيظهر لك SHOW CREATE TABLE لمُختلف الجداول التي يحويها هذا الملف.

6.3 إهمال الإسكيما و التحكم بالكود المصدري source control

لأن أوامر إهمال الإسكيما هي المُنحكم الرئيسي بالإسكيما الخاصة بقاعدة البيانات. لذلك يُنصح بشدة بأن تتأكد من وجودهم بلوحة تحكم المصدر الخاصة بك. إن ملف db/schema.rb يحتوي على النُسخة الحالية من قاعدة البيانات الخاصة بك. هذا يؤكد حدوث الأخطاء عند دمج العديد منها. و حل هذا الأخطاء يكون يدويًا بإبقاء النُسخة الأعلى من المدمجين.

7 Active Record و التكامل المرجعي referential integrity

اقتباس

التكامل المرجعي: هو دمج العديد من قواعد البيانات معًا.

إن Active Record يدعي أن هُناك آلية ذكية في النماذج الخاصة بقواعد البيانات و ليس بقواعد البيانات نفسها. مثل المميزات triggers و constraints التي تضيف هذه الآلية إلى قاعدة البيانات نفسها, و لكنها ليست مُستخدمة بكثرة. التحقيقات مثل validates:foreign_key و uniqueness: true هي التي تُستخدم عن تكامل البيانات بين قواعد البيانات. فأمر dependent: في القواعد المُتصلة يسمح بتدمير الكائن المورَث عند تدمير الكائن المورِث. هذا لا يُمكن ضمان حدوثه في التكامل المرجعي بوجود تحقيقات المفاتيح الأجنبية في قاعدة البيانات. و مع ذلك فإن Active Record لا يوفر جميع الأدوات التي تعمل مُباشرةً مع هذه المميزات، لذلك فإنه يُمكنك إستخدام أمر excute لتنفيذ أوامر SQL.

8 التهجير و البيانات المرجعية seed data

حتى لا ننسى أن الهدف الأساسي من خاصية التهجير و هو عمل أوامر تُعدل على الإسكيما بإستخدام أوامر ثابتة و مُتسقة. إن التهجير أيضًا يُمكن إستعماله لإضافة أو تعديل البيانات، و هذا مُفيد في قواعد البيانات الموجودة مُسبقًا التي لا يُمكن تدميرها و إعادة صُنعها. مثل تلك قاعدة البيانات الخاصة بالإنتاج:

class AddInitialProducts < ActiveRecord::Migration[5.0]
  def up
    5.times do |i|
      Product.create(name: "Product ##{i}", description: "A product.")
    end
  end

  def down
    Product.delete_all
  end
end

لإضاافة بيانات أولية seed data بعد صُنع قاعدة البيانات. إن Rails لديها دالة داخلية built-in تُساعد على تسهيل تلك العملية. خصيصًا عند إعادة تحميل قواعد البيانات بشكل مُتكرر أثناء التطوير و الإختبار. يُمكنك إستخدام تلك الخاصية بكتابة أكواد ruby التي تريدها في ملف db/seeds.rb ثُم تشغيل أمر rails db:seed

5.times do |i|
  Product.create(name: "Product ##{i}", description: "A product.")
End

و يُمكنك إستخدام تلك الخاصية لإعداد قاعدة بيانات فارغة من البداية.
وبذلك نكون قد أنهينا هذه السلسلة المخصصة لتعلّم تهجير Active Record في إطار العمل روبي أون ريلز.

المصدر:
توثيقات Ruby on Rails.

في الدرس السابق ألقينا نظرة عامة على تهجير Active Record وكيفية إنشائه وسنتابع في هذا الدرس تعلّم كيفية كتابة أوامره عبر صنع الجداول وتعديلها وغيرها.

3 كتابة أوامر التهجير

بمجرد استخدامك للمولدات لتوليد التهجير، فسيتحتم عليك البدء بالعمل الحقيقي و كتابة أوامر التهجير.

3.1 صُنع الجداول

إن دالة create_tables هي الأساسية لصنع الجداول، و لكن في مُعظم الأوقات ستقوم المولدات بإنتاج تلك الجداول كما رأينا في الأمثلة السابقة. مثال على صُنع جدول

create_table :products do |t|
  t.string :name
end

وهذا سوف يصنع جدول يُسمى products يحتوي على عامود نصي يُسمى name (وعامود مُفتاح رئيسي يُسمى id يتولد تلقائيًا كما ناقشنا من قبل) و تلقائيًا، ستنتج دالة create_table ستصنع عامود مُفتاح رئيسي id. يُمكنك تغيير إسم هذا المُفتاح باستخدام أمر primary_key: (ولا تنسَ أن تقوم بهذا التغيير في بقية النماذج models)، كما يُمكنك إلغاء وجود ذلك المُفتاح إن لم تحتاجه بإستخدام أمر id: false. أما إذا أردت تعديل تخطي بعض الخيارات الأخرى لقاعدة البيانات، فيُمكنك استخدام سطور SQL في خيار options: وعلى سبيل المثال:

create_table :products, options: "ENGINE=BLACKHOLE" do |t|
  t.string :name, null: false
end

وهذا الكود سوف يُضيف ENGINE = BLACKHOLE إلى سطور SQL المسؤولة عن صُنع الجداول ( وفي حالة استعمال MySQL أو MariaDB، فإن الكود المُستخدم هو ENGINE = InnoDB). يُمكنك تعدي خيار comment: باستخدام أي وصف للجدول مُخزن في قاعدة البيانات نفسها و سيتم ظهور هذا الوصف أدوات إدارة قاعدة البيانات، مثل MySQL Workbench أو PgAdmin III. كما أنه من المُفضل لتوضيح التعليقات comments في التهجيرات المُستخدمة بتطبيقات قواعد البيانات الكبيرة. حيث سُتساعد من يقرأ قاعدة البيانات لفهم نماذج البيانات و عمل التوثيقات اللازمة لقاعدة البيانات.

3.2 صُنع الجداول المُدمجة

إن دالة التهجير creat_join_table تقوم بصُنع جداول مُدمجة (HABTM-has and belongs to many) و التي كما عرفناها سابقًا عبارة عن عدة عواميد من جدول واحد أو جداول مُختلفة. مثال:

create_join_table :products, :categories

و هذا سوف يصنع جدول categories_products يحتوي على عامودين يُسميان category_id و product_id. وهذه العواميد تلقائيًا تُعطي قيمة false للأمر null: و يُمكن تخطي هذا الأمر بالتعديل على الخيار column_options:، مثال:

create_join_table :products, :categories, column_options: { null: true }

إسم الجدول المُدمج سيتكون من إسم العواميد المكونة له طبقًا لترتيبها الأبجدي، و لتغير ذلك يُمكنك إستخدام قواعد التسمية المُستخدمة في المقال السابق و بدالة table_name:، مثال:

create_join_table :products, :categories, table_name: :categorization

مما سينتج عن الكود السابق جدول يُسمى categorization. كما أن دالة create_join_table يُمكنها إضافة الفهارس و العواميد الإضافية (و لا يتم عمل ذلك بشكل تلقائي إذ يجب عليك تحديد الفهارس أو العواميد الإضافية) مثال:

create_join_table :products, :categories do |t|
  t.index :product_id
  t.index :category_id
end

3.3 تغيير الجداول

إن دالة تغيير الجداول change_table مُشابهة لدالة صُنعها create_table عدا أن الثانية تُستخدم لتغير جداول موجودة مُسبقًا. و تعمل بنفس الطريقة و لكنك لن تحتاج إعادة تعريف كُل شيئ لأنه سيأخُذها من الجدول المُتغير منه. مثال على ذلك:

change_table :products do |t|
  t.remove :description, :name
  t.string :part_number
  t.index :part_number
  t.rename :upccode, :upc_code
end

الكود السابق سوف يحذف العواميد description و columns. و سيصنع عامود نصي part_number وسيضيف فهرس إليه، و سيقوم أيضًا بإعادة تسمية عامود upccode.

3.4 تغيير الأعمدة

توفر Rails أمر التهجير change_column و الذي يؤدي دور الأوامر remove_column و add_column.

change_column :products, :part_number, :text

الكود أعلاه سيُغير نوع العامود part_number في الجدول products ليُصبح حقل نصوص texts. لاحظ أن الدالة change_column لا يُمكن عكسها. وبجانب دالة change_column يوجد دوال change_column_null و change_column_default التي تُستخدم تحديدًا لتغيير القيم الإفتراضية default values للعامود.

change_column_null :products, :name, false
change_column_default :products, :approved, from: true, to: false

الكود أعلاه سيقوم بتغيير الحقل name: في جدول products ليُصبح من نوع NOT NULL و القيمة الإفتراضية لحقل approved: من true إلى false.

اقتباس

مُلاخظة: يُوجد طريقة أخرى لكتابة أمر التهجير change_column_default و هي change_column_default :products, :approved, false و لكن هذه الطريقة لا يُمكن عكسها irreversible عكس المُستخدمة في الكود أعلاه.

3.5 مُعدلات الأعمدة

إن مُعدلات الأعمدة Column Modifiers يُمكن أن تُطبق عند صُنع أو تغيير العواميد:

• limit : يقوم بتحديد أقصى مساحة للحقول من الأنواع string/text/binary/integer
• Precision : يُحدد دقة الأرقام العشرية بتحديد عدد الوحدات في الرقم الواحد قبل العلامة العشرية
• Scale : يُحدد دقة الأرقام العشرية بتحديد عدد الوحدات في الرقم الواحد بعد العلامة العشرية
• Polymorphic : يُضيف عامود type إلى رابطة belong_to
• Null : تسمح بإستخدام قيمة NULL أو عدم إستخدامها بالعامود.
• Default : يُتيح لك بتعيين قيمة إفتراضية بالعامود. مع مُلاحظة أنه عند إستخدامك قيمة ديناميكية (مثل التاريخ، فإنه سيتم تعيين القيمة الإفتراضية للتاريخ الذي تم صُنع التهجير عنده.
• Index : يُضيف فهرس للعامود
• Comment : يُضيف تعليق للعامود

بعض المحولات adapters تدعم بعض الخيارات الإضافية: يُمكنك رؤية التوثيقات الخاصة بتلك المحولات لمعرفة المزيد عن هذا الأمر.

اقتباس

**لاحظ أنه أمري null و support لا يُمكن تحديدهم بإستخدام واجهة الأوامر Command Line

3.6 المفاتيح الأجنبية

على الرغم من عدم إضطرارك لإضافة المفاتيح الأجنبية Foreign Keys إلا أنه يُمكنك فعل ذلك لضمان السلامة المرجعية لقاعدة البيانات.

add_foreign_key :articles, :authors

هذا سوف يُضيف مفتاح أجنبي جديد إلى عامود author_id في جدول articles. والمفتاح سيرمز إلى عامود id في جدول authors. أما إذا كانت أسماء الأعمدة لا يُمكن إشتقاقها من أسماء الجداول، فيُمكنك إستخدام الأوامر column: و primary_key:. إن Rails أيضًا ستقوم بتوليد إسم إفتراضي لكُل مُفتاح أجنبي، سيبدأ بـ fk_rails_ ثُم سيُتبع بعشرة حروف التي ستتولد تلقائيًا من أمر from_table و column. و يُمكنك أيضًا إستخدام name: لتعيين إسم مُختلف إذا أردت.

اقتباس

**ملحوظة: إن Active Record يدعم عامود واحد من المفاتيح الأجنبية foreign keys. عدا ذلك يُمكنك إستخدام ملف excute.sql أو structre.sql لإستخدام العديد منها.

حذف المفاتيح الأجنبية لهو أمر سهل أيضًا:

# let Active Record figure out the column name
remove_foreign_key :accounts, :branches

# remove foreign key for a specific column
remove_foreign_key :accounts, column: :owner_id

# remove foreign key by name
remove_foreign_key :accounts, name: :special_fk_name

3.7 إستخدام دالة التغيير change

إن دالة التغيير change هي الطريقة الأساسية لكتابة أوامر التهجير (حيث كما علمنا فإن التهجير هو عبارة عن تغيير في الأساس). و في أغلب الحالات، فإن Active Record يُمكنه عكس تلك التهجيرات. حاليًا، يُمكنك إستخدام دالة التغيير على الدوال الآتية:

• add_column
• add_foreign_key
• add_index
• add_reference
• add_timestamps
• change_column_default (must supply a :from and :to option)
• change_column_null
• create_join_table
• create_table
• disable_extension
• drop_join_table
• drop_table (must supply a block)
• enable_extension
• remove_column (must supply a type)
• remove_foreign_key (must supply a second table)
• remove_index
• remove_reference
• remove_timestamps
• rename_column
• rename_index
• rename_table

دالة change_table يُمكن عكسها في حالة أن الجدول لا يقوم بإستدعاء دالة change أو change_default أو remove. ودالة remove_column أيضًا يُمكن عكسها إذا قُمت بتوفير نوع العامود كعامل ثالث موفرًا أيضًا باقي خيارات العامود. وبدون ذلك فإن Rails لن تتمكن من عمل العامود عند إستخدام الأوامر العكسية:

remove_column :posts, :slug, :string, null: false, default: '', index: true

أما إذا أُضطررت لإستعمال دوال أخرى فعليك إستعمال أمر reversible أو كتابة أوامر up و down بدلًا من إستعمال دالة change.

3.9 إستعمال أمر العكس reversible

إن التهجيرات المُعقدة تتطلب مُعالجة لا يستطيع Active Record عكسها. لذلك يُمكنك إستخدام أمر reversible لتحديد ماذا يحدث عند تشغيل التهجير و ماذا يحدث عند عكسه، مثال:

class ExampleMigration < ActiveRecord::Migration[5.0]
  def change
    create_table :distributors do |t|
      t.string :zipcode
    end

    reversible do |dir|
      dir.up do
        # add a CHECK constraint
        execute <<-SQL
          ALTER TABLE distributors
            ADD CONSTRAINT zipchk
              CHECK (char_length(zipcode) = 5) NO INHERIT;
        SQL
      end
      dir.down do
        execute <<-SQL
          ALTER TABLE distributors
            DROP CONSTRAINT zipchk
        SQL
      end
    end

    add_column :users, :home_page_url, :string
    rename_column :users, :email, :email_address
  end
end

إن إستعمال دالة reversible سوف تتأكد من تنفيذ excute سطور الكود في الترتيب الصحيح. ففي المثال السابق، سيتم عكس التهجير بالترتيب، فسيتم تشغيل البلوك down بعد حذف عامود home_page_url و قبل إضافة جدول distributors. في بعض الأحيان، لن يُمكن عكس عملية التهجير. لأنه –وعلى سبيل المثال- قد تؤدي إلى تدمير بعض البيانات. في هذه الحالات يُمكنك إستخدام أمر ActiveRecord::IrreversibleMigration في البلوك down. و إذا حاول أحد عكس التهجير فإن رسالة خطأ error message ستُخبره بأن هذا الأمر غير مُمكن.

3.10 إستعمال دوال up/down

يُمكنك إستعمال الأسلوب القديم للتهجير بدوال up و down بدلًا من إستعمال دالة change. فإن دالة up يجب أن تصف فيها التغيرات التي تريد عملها في الإسكيما. و دالة down ستقوم بعكس التغيير الذي قامت به دالة up. بإختصار، فإنك إذا قُمت بتطبيق دالة up ثُم بعد ذلك دالة down فيجب ألا يحدث تغيير على قاعدة البيانات. و من المُرجح أن تكون التغييرات التي ستقوم بها دالة up يُمكن عكسها بسهولة. المثال السابق ذكره في قسم (3.9 أمر العكس) سيؤدي وظيفته هذا المثال:

class ExampleMigration < ActiveRecord::Migration[5.0]
  def up
    create_table :distributors do |t|
      t.string :zipcode
    end

    # add a CHECK constraint
    execute <<-SQL
      ALTER TABLE distributors
        ADD CONSTRAINT zipchk
        CHECK (char_length(zipcode) = 5);
    SQL

    add_column :users, :home_page_url, :string
    rename_column :users, :email, :email_address
  end

  def down
    rename_column :users, :email_address, :email
    remove_column :users, :home_page_url

    execute <<-SQL
      ALTER TABLE distributors
        DROP CONSTRAINT zipchk
    SQL

    drop_table :distributors
  end
end