Yii هو إطار PHP عالي الأداء يعتمد على المكونات لتطوير تطبيقات الويب الحديثة بسرعة.
إن الاسم "Yii" (يُنطق بـ "يي" أو "[جي:]" يعني "بسيطًا وتطوريًا" باللغة الصينية. ومن الممكن ايضا
اعتباره اختصارًا لـ Yes It Is!
#
ما هي أفضل التطبيقات أو البرمجيات التي يمكن برمجتها وتتناسب مع ال Yii
Yii هو إطار عام لبرمجة الويب ، مما يعني أنه يمكن استخدامه لتطوير كافة أنواع
تطبيقات الويب باستخدام PHP. وذلك بسبب البنية القائمة على البنية التركيبة لبيئة العمل وترابطها مع المكونات والتخزين المؤقت، وهو مناسب بشكل خاص لتطوير portals, forums, content management systems (CMS), e-commerce projects, RESTful Web services. وما إلى ذلك.
#
كيف يمكن مقارنة بيئة العمل الخاصة بال Yii مع الأطر أو بيئات العمل الأخرى؟
إذا كنت بالفعل على دراية بإطار العمل الأخرى ، فيمكنك معرفة كيف تتم مقارنة ال Yii:
مثل معظم أطر عمل ال PHP ، يطبق Yii النمط المعماري MVC (Model-View-Controller).
ال Yii يتبنى الفلسفة التي تقول أن الشيفرة البرمجية يجب أن تكتب بأسهل طريقها وادقها، ولكنها بذات الوقت يجب أن تكون أنيقة الكتابة مظهرا ومضمونا (شكلا وتطيبقا).
ال Yii هو إطار متكامل (full stack) يوفر العديد من الميزات الجاهزة للإستخدام والمعدة مسبقا، مثل ال query builders وال ActiveRecord لقواعد البيانات العلاقئية (relational) وغير العلائقية (Nosql)، بالإضافة الى دعم وتجهيز ال RESTful API والتخزين المؤقت (caching) وغيرها الكثير.
من مميزات ال Yii إمكانية التعديل (استبدال جزء معين أو تخيصيص وإضافة) جزء معين على أغلب ال Yii core code، وبالإضافة الى هذا، يمكنك بناء ملحقات برمجية اعتمادا على ال core code، ومن ثم نشر هذه الشيفرة وتوزيعها واستخدامها دون وجود أي مشاكل أو صعوبة تذكر.
الأداء العالي هو الهدف الأساسي من ال Yii.
ال Yii إطار عمل صمم من قبل فريق برمجي متكامل، فهو ليس مجرد عمل فردي ، بل يتكون من فريق تطوير أساسي وقوي ، بالإضافة إلى منتدى كبير
من المهنيين الذين يساهمون باستمرار في تطوير هذا الإطار. فريق المطورين الخاص بال Yii
يراقب عن كثب أحدث اتجاهات تطوير الويب وأفضل الممارسات والمميزات التي
وجدت في الأطر والمشاريع الأخرى. وتدرج بانتظام بإضافة أفضل الممارسات والميزات الى ال Yii عبر واجهات بسيطة وأنيقة.
#
الإصدارات الخاصة بال Yii
يتوفر لدى Yii حاليًا إصداران رئيسيان: 1.1 و 2.0. الإصدار 1.1 هو الجيل القديم وهو الآن في وضع الصيانة. الإصدار 2.0 هو إعادة كتابة وهيكلة كاملة لل Yii، تم اعتماد أحدث التقنيات والبروتوكولات فيها مثل including Composer, PSR, namespaces, traits والكثير من الأمور الأخرى، وفي هذه الإرشادات، سيكون الكلام كله موجها الى الإصدار الثاني من بيئة العمل ال Yii.
#
المتطلبات الأساسية للعمل على إطار ال Yii
الإصدار PHP 7.4.0 أو أكثر
المعرفة الأساسية بمفاهيم البرمجة كائنية التوجه OOP
المعرفة بآخر وأحدث التقنيات الموجودة بال php مثل ال namespaces, traits، الفهم لهذه المفاهيم سيسهل عليك العمل كثيرا
ملاحظة: يمكن التحقق من توافق المتطلبات الخاصة بك مع ال yii من خلال الدخول الى الصفحة requirement الموجودة بال yii
---
### Guide Ar Start Databases (`docs/guide-ar/start-databases.md`)
#
التعامل مع قواعد البيانات
في هذا الجزء التعليمي ستتعلم آلية إنشاء صفحة جديدة تعرض بيانات يتم جلبها من قاعدة البيانات -في هذا المثال، البيانات تخص ال country-، هذه البيانات سيتم جلبها من جدول موجود في قاعدة البيانات يسمى ب country. لتحقيق هذا المهمة، ستقوم بعمل ال config الخاص بالإتصال بقاعدة بيانات، بالإضافة لإنشاء ال Active Record class، وتعريف ال action، وإنشاء view لهذه الصفحة.
في هذا الشرح ستتعلم كيف يمكنك القيام بما يلي:
إعداد ال connection الخاص بقاعدة البيانات
التعرف على ال active record.
إنشاء جمل إستعلام عن البياتات بإستخدام ال active record class
عرض البيانات داخل ال view من خلال ال paginated fashion.
ملاحظة: من أجل الانتهاء من هذا الجزء التعليمي، يجب أن يكون لديك المعرفة الأساسية والخبرة باستخدام قواعد البيانات. وعلى وجه الخصوص، يجب أن تعرف كيفية إنشاء قواعد البيانات، وكيفية تنفيذ ال statements SQL باستخدام أي DB client tool.
##
إعداد قاعدة البيانات
في البداية، عليك إنشاء قاعدة بيانات تسمى ب yii2basic، والتي ستستخدم لجلب البيانات الخاصة بالتطبيق، ويمكنك إستخدام أي من ال SQLite, MySql, PostgreSQL, MSSQL or Oracle database, ال Yii بشكل افتراضي بدعم العديد من قواعد البيانات والتي يمكنك إستخدامها مباشرة في التطبيق الخاص بك، ولتبسيط الأمور، ال MySql هي التي سيتم إستخدامها في في هذا الشرح.
معلومة: إذا كنت ترغب بالحصول على خيارات متقدمة مثل دعم ال JSON الموجود داخل MariaDB، فيمكنك من إستخدام أحد ال Extension المذكوره بالأسفل للقيام بهذه المهمة بدلا من الإستغناء عن ال MySql، فإستخدام MariaDB بدلا عن ال MySql لم يعد صحيحا تماما.
بعد قيامك بإنشاء قاعدة البيانات، سنقوم بإنشاء جدول إسمه country، ومن ثم سنقوم بإدخال بعض البيانات كعينة للإختيار، وللقيام بذلك، قم بتنفيذ الأوامر التالية:
```sql
CREATE TABLE `country` (
`code` CHAR(2) NOT NULL PRIMARY KEY,
`name` CHAR(52) NOT NULL,
`population` INT(11) NOT NULL DEFAULT '0'
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
INSERT INTO `country` VALUES ('AU','Australia',24016400);
INSERT INTO `country` VALUES ('BR','Brazil',205722000);
INSERT INTO `country` VALUES ('CA','Canada',35985751);
INSERT INTO `country` VALUES ('CN','China',1375210000);
INSERT INTO `country` VALUES ('DE','Germany',81459000);
INSERT INTO `country` VALUES ('FR','France',64513242);
INSERT INTO `country` VALUES ('GB','United Kingdom',65097000);
INSERT INTO `country` VALUES ('IN','India',1285400000);
INSERT INTO `country` VALUES ('RU','Russia',146519759);
INSERT INTO `country` VALUES ('US','United States',322976000);
```
الآن، أصبح لديك قاعدة بيانات إسمها yii2basic، وتحوي بداخلها جدول بثلاث أعمدة يسمى ب country، وفيه 10 صفوف من البيانات.
##
إعدادات الإتصال الخاصة بقواعد البيانات - Configuring a DB Connection
قبل أن تكمل الشرح، تأكد من تثبيت ال PHP PDO وال PDO driver، بالنسبة لهذا المثال، فإننا سنستخدم ال driver الخاص بال MySql وهو ال pdo_mysql، وهذه هي المتطلبات الأساسية لبناء أي التطبيق اذا كان التطبيق يستخدم ال relational database.
ملاحظة: يمكنك تقعيل ال PDO مباشرة من خلال الدخول الى php.ini ومن ثم حذف الفاصلة المنقوطة قبل السطر التالي: extension=php_pdo.dll
كما يمكنك تفعيل ال driver المطلوب عن طريق حذف الفاصلة المنقوطة قبل ال driver المقصود مثل:
extension=php_pdo_mysql.dll
ويمكنك الإطلاع على المزيد من هنا:
pdo installation
بعد إتمام ما سبق، قم بفتح الملف config/db.php ومن ثم قم بتعديل ال parameters لتكون الإعدادات الخاصة بقاعدة البيانات صحيحة -الإعدادت الخاصة بك-، بشكل افتراضي، يحتوي الملف على ما يلي:
يمثل ملف ال config/db.php أداة نموذجية تعتمد على الملفات للقيام بال configuration. يقوم ملف ال configuration بتحديد ال parameters المطلوبة لإنشاء وإعداد ال instance الخاص بال [[yii\db\Connection]]، ومن خلالها يمكنك إجراء عمليات الإستعلام على قاعدة البيانات.
الإعدادات الخاصة بالإتصال بقاعدة البيانات والمذكورة في الملف أعلاه يمكن الوصول اليها من خلال التطبيق عن طريق تنفيذ الأمر التالي
Yii::$app->db
معلومة: سيتم تضمين ملف ال config/db.php من خلال ال main application configuration والذي يتمثل بالملف config/web.php، والذي يقوم بدوره بتحديد كيف يمكن تهيئة ال instance الخاص بالتطبيق، لمزيد من المعلومات، يرجى الإطلاع على قسم ال Configurations.
إذا كنت بحاجة إلى العمل مع إحدى قواعد البيانات الغير مدعومة بشكل إفتراضي من ال Yii، فيمكنك التحقق من الإضافات التالية:
لجلب البيانات وعرضها من جدول ال country، سنقوم بإضافة ال Active Record الى ال class المسمى ب country، والموجود في المسار models/Country.php.
```php
يرث ال Country Class ال [[yii\db\ActiveRecord]]، ولذلك، أنت لست بحاجة لكتابة أي شيفرة برمجية بداخله، فقط الشيفرة التي تشاهدها بالأعلى. سيقوم ال Yii بشكل تلقائي بالحصول على إسم الجدول في قاعدة البيانات من خلال إسم ال Class.
معلومة: إذا لم يكن من الممكن إجراء مطابقة مباشرة بين اسم ال class واسم الجدول، فيمكنك تجاوز هذه المشكلة من خلال إستخدام الدالة [[yii\db\ActiveRecord::tableName()]] ، والتي ستقوم بعمل override على اسم الجدول.
من خلال إستخدام ال Country class، يمكنك التحكم بكل سهولة بالبيانات الموجودة داخل جدول ال country، شاهد هذه الشيفرة البرمجية لتبسيط الفكرة:
```php
use app\models\Country;
// get all rows from the country table and order them by "name"
$countries = Country::find()->orderBy('name')->all();
// get the row whose primary key is "US"
$country = Country::findOne('US');
// displays "United States"
echo $country->name;
// modifies the country name to be "U.S.A." and save it to database
$country->name = 'U.S.A.';
$country->save();
```
معلومة: يعتبر ال Active Record وسيلة قوية للوصول إلى بيانات قاعدة البيانات والتعامل معها بطريقة ال object oriented.
ستجد معلومات أكثر تفصيلاً في الجزء الخاص بال Active Record. بالإضافة الى ذلك، يمكنك التفاعل مباشرة مع قاعدة البيانات باستخدام lower-level data accessing والتي تسمى ب Database Access Objects.
##
إنشاء ال Action
لعرض بيانات ال country للمستخدمين، يلزمك إنشاء action جديد، وبدلاً من وضع ال action الجديد في ال site controller كما فعلنا في المرات السابقة، سنقوم بإنشاء controller جديد، ومن ثم سنقوم بوضع ال action بداخله، والسبب المنطقي لهذا العمل أنك ستقوم بتجميع الشيفرة البرمجية المسؤولة عن أداء وظائف معينة في مكان واحد، وبهذا فإن جميع الإجرائات التي تخص ال country من المنطقي أن تكون موجودة داخل ال CountryController، والآن لنقم بإنشاء هذا ال controller الجديد، وال action الجديد وسيكون باسم index، كما هو موضح أدناه:
قم بحفظ الشيفرة البرمجية التي بالأعلى داخل هذا الملف controllers/CountryController.php
يقوم ال index action باستخدام ال Country::find()، وهذه الدالة موجودة من ضمن ال active record، وتقوم هذه الدالة على بناء الإستعلام الخاص بقاعدة البيانات مما يسمح باسترجاع جميع البيانات الموجودة بداخل جدول ال country، ولتحديد الحد الأعلى المسموح إرجاعه في كل request، يمكنك إستخدام ال [[yii\data\Pagination]] object كوسيلة مساعدة، ويقدم هذا ال object غرضين أساسيين وهما:
كتابة جملة استعلام محددة بعدد صفوف معين، وتبدأ من مكان معين، ويتم ذلك من خلال ال offset وال limit، وبهذا التعيين فأنت ستقوم بإرجاع صفحة واحدة من البيانات وفي كل مرة سيتم عرض 5 صفوف على الأكثر.
كما يستخدم في صفحة ال view لعرض ال pager مع قائمة بال page buttons، وذلك كما ستشاهد في الجزء التالي من هذا الموضوع.
في نهاية الشيفرة البرمجية الموجودة في ال index action، نقوم باستدعاء صفحة ال view المسمية ب index، ومن ثم نقوم بإرسال معلومات ال country المنظمة على شكل صفحات (pagination) ومن ثم عرضها.
##
إنشاء View
الآن، سنقوم بإنشاء صفحة ال view والتي ستقوم بعرض المعلومات الخاصة بال country والقادمة من ال index action، ولذلك توجه الى المسار views, ومن ثم قم بإنشاء مجلد جديد بداخله باسم country، هذا المجلد سيحوي جمع ال views التي سيتم إستدعائها من ال country controller>. الآن، قم بإنشاء الصفحة index.php بداخل المسار views/country، ومن ثم قم بكتابة هذه الشيفرة البرمجية بداخلها:
```php
Countries
code} ({$country->name})") ?>:
population ?>
$pagination]) ?>
```
في هذه الصفحة، هناك جزئيين رئيسيين، الجزء الأول هو المسؤول عن طباعة المعلومات الخاصة بال country داخل قائمة من نوع ul، والجزء الثاني عبارة عن widget يستخدم المعلومات الخاصة بال pagination والتي تم إرسالها من ال action، ليقوم بعد ذلك بعرض قائمة من ال page buttons، والتي بدورها ستقوم بعمل تحديث للمعلومات الموجودة بالصفحة بنائا على الصفحة المطلوبة، هذا ال widget يسمى ب LinkPager -[[yii\widgets\LinkPager]]-.
##
لنجرب المثال
لتشاهد آلية العمل لهذا المثال، والنتائج المتعلقة به، يمكنك إستخدام المتصفح والدخول الى الرابط التالي:
في البداية، ستشاهد البيانات الخاصة بخمسة دول، وأسفل هذه الدول، ستشاهد pager فيه 4 أزرار، اذا قمت بالضغط على الزر رقم 2، فإنك ستشاهد المعلومات الخاصة بخمسة دول أخرى، والتي تمثل صفوف أخرى من البيانات تم جلبها من قاعدة البيانات.
تابع بعناية أكبر وستجد أن عنوان ال URL في المتصفح قد تغير أيضًا:
بالخفاء، يقوم ال [[yii\data\Pagination|Pagination]] بتقديم الدعم اللازم لكل الوظائف المطلوب تنفيذها لعمل الترقيم الخاص بال pagination:
في البداية، يمثل ال [[yii\data\Pagination|Pagination]] الصفحة الأولى التي تعكس جملة الإستعلام SELECT مع الجدول country مع العبارة LIMIT 5 OFFSET 0. ونتيجة لذلك، سيتم جلب البلدان الخمسة الأولى وعرضها.
ال [[yii\widgets\LinkPager|LinkPager]] widget يقوم على إستدعاء الأزرار الخاصة بأرقام الصفحات والتي يتم إنشاء ال Url الخاص بها من خلال ال [[yii\data\Pagination::createUrl()|Pagination]]، هذه ال Url تحتوي على parameter يسمى ب page، والذي يمثل بدورة مجموعة من الأرقام المختلفة والتي تمثل صفحات تعرض بيانات مختلفة كما هو في مثالنا عندما قمنا بالضغط على رقم 2.
عند قيامك بالنقر على الزر رقم 2، سينطلق request جديد الى ال country/index route، وحينها يقوم ال [[yii\data\Pagination|Pagination]] على قرائة ال page parameter من ال URL ,من ثم يقوم بتغيير رقم الصفحة الحالية الى الرقم الجديد، وهنا الرقم الجديد هو 2 بدلا من 1. كما أن جملة الإستعلام الجديدة ستحوي الشرط التالي LIMIT 5 OFFSET 5 لتقم بذلك بجلب الصفوف الخمسة الأخرى من البلدان لعرضها.
##
الخلاصة
في هذا الجزء من التوثيق، لقد تعلمنا كيف يمكننا التعامل مع قواعد البيانات، وكيف يمكننا جلب البيانات وعرضها وتجزئتها لصفحات من خلال إستخدام ال [[yii\data\Pagination]] وال [[yii\widgets\LinkPager]].
في الجزء القادم من هذا التوثيق، ستتعلم كيف يمكنك إستخدام إخدى الوسائل المميزة والموجودة في ال Yii لإنشاء الشيفرة البرمجية الخاصة بك، والتي يطلق عليها اسم Gii، هذه الأداة ستساعدك على إنشاء وتنفيذ الشيفرات البرمجية التي يكثر كتابتها وإستخدامها بشكل دوري، مثل مجموعة العمليات Create-Read-Update-Delete، والتي يتم اختصارها ب CRUD، هذه الأداة ستقوم بالتعامل مع البيانات الموجدة بقاعدة البيانات، وفي الحقيقة، الشيفرة البرمجية الذي قمت بكتابته بالأعلى، يمكنك إنشائه بسهولة من خلال ال Gii بنقرة زر، لذلك فلننطلق الى الجزء التالي بأسرع وقت.
---
### Guide Ar Start Forms (`docs/guide-ar/start-forms.md`)
#
العمل مع ال Forms
في هذا الموضوع سنتعلم كيفية إنشاء صفحة تحتوي على form للحصول على البيانات من خلال المستخدمين، وستعرض هذه الصفحة form يحتوي على حقل لإدخال الإسم وحقل إدخال للبريد الإلكتروني.
وبعد الحصول على المعلومات الخاصة بهذه الحقول من المستخدم، ستقوم الصفحة بطباعة القيم التي تم إدخالها.
في هذا الشرح، ستقوم بإضافة action وصحفتين views، وستتعرف أيضا على طريقة إنشاء ال model.
من خلال هذا البرنامج التعليمي ، ستتعلم كيفية:
إنشاء model لتمثيل البيانات التي تم إدخالها من خلال المستخدم عن طريق ال form.
إنشاء rules للتحقق من صحة البيانات التي تم إدخالها.
بناء html form داخل صفحة ال view.
##
إنشاء ال Model
يتم تمثيل البيانات التي يتم طلبها من خلال المستخدم عن طريق ال EntryForm model class كما هو موضح أدناه، ويتم حفظ هذا الملف داخل المسار models، ويكون إسم ال model ومساره في مثالنا هذا هو models/EntryForm.php. يرجى الرجوع إلى صفحة ال Class Autoloading للحصول على مزيد من التفاصيل حول طريقة التعامل مع التسمية الخاصة بال class في Yii.
```php
هذا ال class يرث ال [[yii\base\Model]], وهو base class تم تصميمه من خلال ال Yii, وبشكل عام وظيفته هي تثمثيل البيانات الخاصة بأي نموذج.
معلومة: يتم إستخدام ال [[yii\base\Model]] كأصل لل model class ولا يرتبط بجداول قواعد البيانات. ويستخدم ال [[yii\db\ActiveRecord]] بالشكل الإعتيادي ليكون هو الأصل الذي من خلاله يتم الإرتباط بجداول بقواعد البيانات.
يحتوي class ال EntryForm على متغيرين إثنين من نوع Public، هما name و email، واللذان يستخدمان في تخزين البيانات التي أدخلها المستخدم. كما يحتوي أيضًا على method باسم rules()، والتي تُرجع مجموعة
الشروط الخاصة بالبيانات للتحقق من صحتها. والشيفرة البرمجية الموجودة داخل ال rules method تعني:
كل من ال name وال email حقول الزامية (required).
ال email حقل يجب أن يحتوي بداخله قيمة صحيحة تعبر عن البريد الإلكتروني (القواعد النحوية لكتابة البريد الإلكتروني).
إذا كان لديك object من ال EntryForm ويحتوي على البيانات التي أدخلها المستخدم، فيمكنك حينها إستدعاء الدالة [[yii\base\Model::validate()|validate()]] للتحقق من صحة البيانات. اذا فشلت عملية التحقق من صحة البيانات، فسيؤدي ذلك إلى تغيير قيمة ال [[yii\base\Model::hasErrors|hasErrors]] إلى true ، بالإضافة الى ذلك يمكنك التعرف الى الأخطاء المتعلقة بهذه البيانات من خلال الدالة [[yii\base\Model::getErrors|errors]].
```php
name = 'Qiang';
$model->email = 'bad';
if ($model->validate()) {
// Good!
} else {
// Failure!
// Use $model->getErrors()
}
```
##
إنشاء Action
الآن، ستحتاج إلى إنشاء action جديد في ال site controller وليكن إسمه entry، والذي سيقوم بدوره باستخدام ال model الجديد الذي قمنا بإنشائه. هذه العملية تم شرحها سابقا في الجزء التالي من التوثيق Saying Hello - قل مرحبا.
```php
load(Yii::$app->request->post()) && $model->validate()) {
// valid data received in $model
// do something meaningful here about $model ...
return $this->render('entry-confirm', ['model' => $model]);
} else {
// either the page is initially displayed or there is some validation error
return $this->render('entry', ['model' => $model]);
}
}
}
```
أولا، يقوم ال action بإنشاء object من ال EntryForm. ثم يحاول تعبئة البيانات لل object من خلال ال $ _POST، والتي يتم تقديمها في ال Yii من خلال ال [[yii\web\Request::post()]].
إذا تم ملء ال object بنجاح (على سبيل المثال، إذا قام المستخدم بإدخال البيانات داخل ال form ومن ثم قام بإرسالها(submitted html form))، فسيتم استدعاء ال [[yii\base\Model::validate()|validate()]] من خلال ال action للتأكد من صلاحية القيم المدخلة.
معلومة: يمثل التعبير Yii::$app ال Application instance الذي يمكن الوصول اليه من خلال ال singleton (singleton globally accessible). وهو أيضا service locator بحيث يوفر الدعم لل components مثل ال request, response, db..الخ، لدعم وظائف محددة. مثلا في المثال الموجود في الأعلى، فإن ال request هو component من ال application instance والذي يستخدم للوصول الى البيانات الموجودة داخل ال $_POST.
إذا كان كل شيء على ما يرام، فسوف يقوم ال action بجلب ال view التالية: entry-confirm، وذلك لتأكيد أن العملية قد تمت بنجاح بالنسبة للمستخدم، أما إن كانت البيانات غير صحيحة، أو لم يتم إرسال أي بيانات، فإن ال view entry هي التي سيتم جلبها وعرضها للمستخدم، حيث يتم عرض ال Html form، مع أي رسائل تحذير بخصوص الأخطاء التي تم العثور عليها من عملية التحقق.
ملاحظة: في هذا المثال البسيط، نعرض صفحة التأكيد فقط عند إرسال البيانات بشكل صحيح. عند الممارسة العملية، يجب عليك استخدام [[yii\web\Controller::refresh()|refresh()]] أو [[yii\web\Controller::redirect()|redirect()]] لتجنب أي مشكلة تحصل عن طريق ال resubmission والتي تندرج تحت العنوان form resubmission problems.
##
إنشاء ال views
أخيرا، سنقوم بإنشاء صفحتين لل views الأولى بإسم entry-confirm والثانية entry. وهاتين الصفحتين سيتم جلبهم من خلال ال entry action.
ال entry-confirm ستقوم بكل بساطة بعرض الإسم والبريد الإلكتروني الذي تم إدخالهم من قبل المستخدم. ويجب حفظ هذه الصفحة بالمسار التالي: views/site/entry-confirm.php
```php
You have entered the following information:
: name) ?>
: email) ?>
```
صفحة ال entry ستقوم بعرض ال HTML form. هذه الصفحة يجب أن يتم حفظها داخل المسار التالي: views/site/entry.php
تستخدم ال view أسلوب مميز لبناء ال Forms، وذلك عن طريق ال widget الذي يسمى ب [[yii\widgets\ActiveForm|ActiveForm]]. إن الأسلوب المستخدم في هذا ال widget يقوم على إستخدام كل من الدالة begin() و end() لجلب ال opening وال closing form tags على التوالي (فتحة ال tag، ثم الإغلاق الخاص بهذا ال tag)، وبين الفتحة والإغلاق يمكنك إنشاء الحقول عن طريق إستخدام الدالة [[yii\widgets\ActiveForm::field()|field()]]. في هذا المثال كان الحقل الأول في ال form يشير الى name data، والثاني يشير الى ال email data، وبعد هذه الحقول ستجد الدالة المستخدمة لإنشاء ال Submit button وهي [[yii\helpers\Html::submitButton()]].
##
لنجرب المثال
لتشاهد آلية العمل لهذا المثال، والنتائج المتعلقة به، يمكنك إستخدام المتصفح والدخول الى الرابط التالي:
```
https://hostname/index.php?r=site%2Fentry
```
عند دخولك الى الرابط السابق، سترى صفحة تعرض Html form يحتوي على حقلين لإدخال المعلومات. أمام كل حقل إدخال ستجد label يشير إلى البيانات المطلوب إدخالها. إذا قمت بالنقر فوق الزر "submit" بدون
أي إدخال، أو إذا لم تقم بكتابة عنوان البريد الإلكتروني بشكل صحيح، فستظهر لك رسالة خطأ بجوار الحقل المقصود.
بعد إدخالك لإسم وبريد الكتروني صحيح، وقيامك بالنقر على زر submit، فإنك ستشاهد صفحة جديدة تقوم بعرض البيانات التي قمت بإدخالها.
##
كيف ظهر الخطأ؟ هل هو سحر؟!
قد تتساءل كيف يعمل ال Html form بالخفاء، وقد يبدو ذلك سحرا للوهلة الأولى، فهو يعرض ال label لكل حقل إدخال، ويعرض رسائل الخطأ إذا لم تقم بإدخال البيانات بشكل صحيح، وكل ذلك دون الحاجة لإعادة تحميل الصفحة.
إن السحر الموجود لدينا هنا، هو كيفية العمل الخاصة بالشيفرة البرمجية لل form، والتي تعمل بالخفاء، إن إجراء التحقق عن صحة البيانات يتم في البداية من جانب العميل -client side- وذلك باستخدام الجافا سكربت، ومن ثم -بعد تجاوز التحقق الخاص بالجافا سكربت- بتم تنفيذ التحقق من جانب ال server-side عبر ال PHP. ال [[yii\widgets\ActiveForm]] ذكية بما فيه الكفاية لاستخراج ال rule الخاصة بالتحقق والتي قمت بإنشائها وتعريفها داخل ال EntryForm، ومن ثم تحويل هذه القواعد إلى شيفرة برمجية بالجافا سكربت قابلة للتنفيذ، ومن ثم استخدام هذه الشيفرة من قبل الجافا سكربت لإجراء التحقق من صحة البيانات. في حال قمت بإيقاف الجافا سكربت في المتصفح الخاص بك، سوف يستمر إجراء التحقق من جانب الخادم -server side-، كما هو موضح في ال action المسمى actionEntry(). وهذا يضمن صحة البيانات في جميع الظروف.
تحذير: التحقق من جانب العميل -client side- يوفر تجربة أفضل للمستخدم، لكن يجب الأخذ بعين الإعتبار أن التحقق من جانب الخادم -server- مطلوب دائمًا، سواء تم التحقق من جانب العميل أم لا.
يتم إنشاء ال labels الخاصة بحقول الإدخال بواسطة الدالة field()، وذلك من خلال إستخدام أسماء ال property الموجودة داخل ال model. على سبيل المثال، سيتم إنشاء ال label التالي Name للproperty التالية: name.
كما يمكنك تعديل ال label الإفتراضي لأي حقل من خلال الشيفرة البرمجية التالية:
معلومة: يوفر ال Yii العديد من ال widgets لمساعدتك في إنشاء views معقدة وديناميكية بسرعة. كما أنك ستتعلم في وقت لاحق كيف يمكنك إنشاء widget جديد، وستكتشف أن الموضوع سهل وبسيط، مما سيدفعك إلى كتابة الشيفرة البرمجية الخاصة بك داخل ال widget، والذي بدوره سيجعل من هذه الشيفرة قابلة للتطوير والإستخدام في أكثر من مكان في المستقبل.
##
الخلاصة
في هذا الجزء من التوثيق، تحدثنا عن كل جزء في ال MVC architectural pattern، لقد تعلمت الآن كيف يمكنك إنشاء model class ليقوم بتمثيل البيانات الخاصة بالمستخدمين، ومن ثم التحقق منها.
لقد تعلمت أيضًا كيفية الحصول على البيانات من المستخدمين، وكيفية عرض البيانات مرة أخرى في المتصفح. هذه المهمة يمكن أن تأخذ الكثير من الوقت عند تطوير أي تطبيق، ولكن، يوفر ال Yii العديد من ال widgets القوية، والتي تجعل من هذه المهمة أمرا سهلا للغاية.
في الجزء القادم من هذا التوثيق، ستتعلم كيف يمكنك التعامل مع قواعد البيانات، والتي سنحتاجها -غالبا- مع كل تطبيق ستعمل عليه تقريبا.
---
### Guide Ar Start Gii (`docs/guide-ar/start-gii.md`)
#
إنشاء الشيفرة البرمجية من خلال ال gii
في هذا الجزء التعليمي سنتعرف على آلية التعامل مع ال Gii، والذي يستخدم لإنتاج الشيفرة البرمجية الخاصة بمعظم الميزات والخصائص المشتركة في أغلب المواقع بشكل تلقائي، بالإضافة الى ذلك، فإن استخدام ال Gii لإنشاء الشيفرة البرمجية بشكل تلقائي يمثل مجموعة من المعلومات الصحيحة التي بتم إدخالها إعتمادا على التعليمات الموجودة في ال Gii Web Pages.
من خلال هذا البرنامج التعليمي، ستتعلم كيفية:
تفعيل ال Gii داخل التطبيق الخاص بك
إستخدام ال Gii لإنشاء ال Active Record class
إستخدام ال Gii لإنشاء الشيفرة البرمجية الخاصة بال CRUD إعتمادا على الجداول الموجودة في قاعدة البيانات
تخصيص (customize) الشيفرة البرمجية التي سيتم إنتاجها من خلال ال Gii.
##
البدء باستخدام ال Gii
يتم تقديم ال Gii داخل على ال Yii على أنه module، ويمكنك تفعيله من خلال الإعدادات الخاصة به والتي تجدها داخل ال application، وبالتحديد داخل ال property التالية [[yii\base\Application::modules|modules]]، واعتمادا على كيفية إنشائك للمشروع، فيمكنك إيجاد الشيفرة البرمجية التالية موجودة بشكل مسبق داخل ال config/web.php:
في الإعدادت الموجودة في الأعلى، فإن التطبيق سيقوم بتضمين وتفعيل ال gii في حال كانت الحالة الخاصة بالتطبيق هي development enviroment، بالإضافة الى ذلك، فإنه يجب تضمين واستخدام ال module gii، والموجود ضمن ال class التالي [[yii\gii\Module]].
اذا قمت بالتحقق من ال entry script وبالتحديد صفحة ال web/index.php في التطبيق الخاص بك، ستجد هذه الأسطر، والتي يجب أن تجعل من ال YII_ENV_DEV ذات قيمة true.
```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```
كل الشكر لهذا السطر البرمجي، التطبيق الآن أصبح بحالة ال development mode، وأصبح لديك ال Gii enabled بالفعل، والآن، يمكنك الوصول الى ال Gii من خلال عنوان ال URL التالي:
```
https://hostname/index.php?r=gii
```
ملاحظة: إذا كنت تحاول الوصول إلى Gii من جهاز آخر غير ال localhost، فسيتم رفض الوصول افتراضيًا لأغراض أمنية، ولكن، يمكنك إعداد ال Gii لإضافة مجموعة من ال IP Addresses المسموح لها بالوصول وذلك من خلال:
لإستخدام ال Gii لإنشاء ال Active Record class, قم باختيار ال "Model Generator" (من خلال النقر على الرابط الموجود بالصفحة الرئيسية لل Gii)، ومن ثم قم بتعبئة ال form كما يلي:
إسم الجدول: country
Country :Model Class
والآن، قم بالنقر على الزر "Preview"، ستشاهد الآن models/Country.php قد تم إنشائها وإضافتها الى قائمة النتائج، اذا قمت بالنقر على إسم ال class، فإن المحتوى الخاص بهذا ال class سيتم عرضه.
عند استخدام ال Gii، إذا كنت قد قمت بالفعل بإنشاء نفس الملف وستقوم بعمل overwriting عليه، فيمكنك النقر على زر diff الموجود بعد إسم ال class، لتشاهد الفرق بين الشيفرة البرمجية الحالية، والشيفرة البرمجية الجديدة.
عند قيامك بعمل overwriting على ملف موجود، قم بالضغط على ال ckeckbox الموجودة بجانب كلمة overwrite، ومن ثم قم بالنقر على زر "Generate", اذا كان هذا الملف جديد، وغير موجود مسبقا، فيمكنك النقر مباشرة على "Generate"، بعد ذلك ستشاهد صفحة ال confirmation والتي تبين الشيفرات البرمجية التي تم إنشائها بنجاح.
بعد فيامك بالنقر على زر Generate، فإنك ستشاهد صفحة ال confirmation page، والتي تقوم بدورها بتوضيح الشيفرات البرمجية التي تم إنشائها بنجاح، واذا كان الملف موجود، فإنك ستشاهد أيضا رسالة تعلمك بأن الملف قد تم تعديله وتمت إضافة الشيفرة الجديدة مكان القديمة.
##
إنشاء ال CRUD Code
ال CRUD هي اختصار ل Create, Read, Update, And Delete (إنشاء، وقرائة، وتحديث، وحذف)، والتي تمثل أكثر المهمات المطلوبة للتعامل مع البيانات على مواقع الويب. ولإنشاء ال CRUD باستخدام ال Gii، قم باختيار ال "CRUD Generator" (من خلال النقر على الرابط الموجود بالصفحة الرئيسية لل Gii)، وهنا وبالبنسبة للمثال الخاص بال "country"، يمكنك تعبئة ال from بما يلي:
* Model Class: `app\models\Country`
* Search Model Class: `app\models\CountrySearch`
* Controller Class: `app\controllers\CountryController`
بعد ذلك، قم بالنقر على زر ال "Preivew"، وستشاهد قائمة بالملفات التي سيتم إنشائها كما في الصورة أدناه.
اذا قمت إنشاء الصفحتين controllers/CountryController.php و views/country/index.php عند حديثنا سابقا عند موضوع (التعامل مع قواعد البيانات)، فقم بالضغط على ال "overwrite" ليتم إستبدالهم. (الصفحات القديمة لا توجد فيها كل الخصائص التي سيتم إنتاجها من خلال ال Gii CRUD).
##
لنجرب المثال
لتشاهد آلية العمل لهذا المثال، والنتائج المتعلقة به، يمكنك إستخدام المتصفح والدخول الى الرابط التالي:
عند دخولك إلى الرابط أعلاه، ستشاهد مجموعة الدول التي تم إستدعائها من جدول ال country من قاعدة البيانات، ويمكنك التعامل مع هذا ال grid من حيث الترتيب أو التصفية بنائا على الشروط التي ستقوم بإدخالها في مربعات النص أعلى الأعمدة.
لكل دولة تم جلبها وعرضها داخل ال Grid، هناك مجموعة من الخيارات التي يمكنك التعامل معها بشكل إفتراضي، مثل ال view لعرض التفاصيل الخاصة بالدولة المختارة، أو تحديث المعلومات، الخاصة بالدولة، أو حذف هذه الدولة، بالإضافة إلى ذلك يمكنك النقر على "Create Country" الموجودة في أعلى ال Grid والتي ستأخذك بدورها الى صفحة تحتوي form لإنشاء ال country.
فيما يلي قائمة بالملفات التي تم إنشاؤها من خلال ال Gii، في حالة رغبتك في التحقق من كيفية عمل هذه الميزات والإطلاع على الشيفرة البرمجية وتخصيصها حسب الرغبة:
معلومة: تم تصميم ال Gii لتكون أداة إنشاء شيفرات برمجية قابلة للتخصيص بشكل كبير للغاية. اذا قمت باستخدامه بحكمة،فإنك ستقوم بتسريع وتيرة التطوير الخاصة بالتطبيق الخاص بك. لمزيد من التفاصيل، يرجى الذهاب إلى الجزء الخاص بال Gii.
##
الخلاصة
في هذا الجزء من التوثيق، لقد تعلمنا آلية استخدام ال Gii لإنشاء الشيفرة البرمجية الخاصة بال CRUD، وتحدثنا عن الوظائف التي تقوم فيها، وكيف يمكننا من خلالها إتمام العمليات الخاصة بالبيانات من إدخال وتحديث وحذف وعرض للبيانات من قاعدة البيانات.
---
### Guide Ar Start Hello (`docs/guide-ar/start-hello.md`)
#
قل مرحبا - Saying Hello
في هذا الموضوع سنتعرف على كيفية إنشاء صفحة "Hello" جديدة في التطبيق الذي قمت بتثبيته، ولتحقيق ذلك، يجب عليك القيام بإنشاء action و view لهذه الصفحة:
سيقوم التطبيق بإرسال ال request الخاص بالصفحة إلى ال action.
وسيقوم ال action بدوره في جلب ال view التي تعرض كلمة "Hello" إلى المستخدم النهائي.
من خلال هذا البرنامج التعليمي ، ستتعلم ثلاثة أشياء:
كيفية إنشاء action ليقوم بإستقبال ال request ومن ثم الرد (respond) عليها.
و كيفية إنشاء التطبيق لل requests التي يوجهها لل actions.
##
إنشاء ال Action
لإنشاء صفحة "Hello"، ستقوم بإنشاء sayaction والذي بدوره سيقوم بقراءة ال message parameter من ال request، ومن ثم عرض ال message مرة أخرى إلى المستخدم. إذا كان ال request لا يحمل معه ال message parameter فإن ال action سيقوم بطباعة message إفتراضية وهي "Hello".
معلومة: ال Actions هي الكائنات(objects) التي يمكن للمستخدمين من الوصول اليها وتنفيذ ما في بداخلها بشكل مباشر. يتم تجميع هذه ال Actions بواسطة ال controllers. ونتيجة لذلك فإن ال response الراجعة للمستخدم ستكون هي نتيجة التنفيذ الخاصة بال action.
يجب تعريف ال actions داخل ال controller، ولتبسيط الفكرة، سنقوم بتعريف ال say action داخل أحد ال controller الموجود مسبقا وهو ال siteController. هذا ال controller ستجده داخل المسار controllers/siteController.php. ومن هنا سنبدأ بإضافة ال action الجديد:
في الشيفرة البرمجية السابقة ، تم تعريف ال say action من خلال إنشاء الدالة actionSay داخل الكلاس siteController. يستخدم ال Yii كلمة action ك prefix للدوال للتميز بين الدوال ال action و ال non-action في ال controller، كما يستخدم الإسم الخاص بال action مباشرة بعد ال prefix، ويتم عمل mapping بين ال action method name وال action id ليستطيع المستخدم من الوصول للدالة المنشئة من خلال ال action id.
عندما يتعلق الأمر بتسمية ال action الخاصة بك، يجب عليك أن تفهم كيف يقوم ال Yii بالتعامل مع ال action id، ال action id يجب أن يكون دائما أحرف lower case، وإذا إحتوى ال action id على عدة كلمات فإن الفاصل بينهم سيكون الداش (dashes) مثل create-comment، ويتم ربط ال action id بال action method name من خلال حذف ال dashes من ال IDs، ويتم عمل capitalizing لأول خرف من كل كلمة، وإضافة ال prefix الى الناتج السابق من التحويل. مثال: ال action id المسمى ب create-comment سيتم تحويله الى ال action method name التالي: actionCreateComment.
في المثال السابق، يقوم ال action method على إستقبال parameter يسمى ب $message، والذي يملك قيمة إفتراضية وهي "Hello" (وهي مشابة تماما لطريقة وضع القيم الإفتراضية لل argument في ال PHP). عندما يستقبل التطبيق ال request ويحدد أن ال action المطلوب للتعامل مع الطلب (request) هو say، فإن التطبيق سيقوم بإسناد القيمة الموجودة بال request الى ال parameter الموجود بال action بشرط أن يكون الإسم الموجود بال request هو نفسه الموجود في ال action. ولتبسيط الموضوع يمكن القول أن ال request اذا احتوى على كلمة message وقيمة هذا ال parameter هي "GoodBye"، فإن ال $message الموجودة في ال action ستصبح قيمتها "GoodBye".
من خلال ال action method، يتم استدعاء ال [[yii\web\Controller::render()|render()]] لتقديم
الملف الخاص بال view والمسمى هنا ب say. أيضا فإن ال message يتم تمرريرها الى ال view مما يسمح لك باستخدام هذا ال parameter داخل ال view. النتيجة المرجعة لل view تتم معالجتها وإرجاعها من خلال ال action method، وهذه النتائج سيتم إستقبالها من خلال المتصفح الخاص بالمستخدم ليتم عرضها وكأنها (جزء من صفحة Html كاملة).
##
إنشاء ال View
ال Views هي شيفرات برمجية كتبت ﻹنشاء المحتوى المناسب بنائا على ال response الراجع اليها من خلال ال action.
بالنسبة إلى مثال "Hello" ، الآن سنقوم بإنشاء view مسمى ب say، والذي سيقوم بدوره بطباعة ال message التي تم إستلامها من ال action، شاهد المثال:
```php
```
صفحة ال view say يجب أن يتم حفظها داخل المسار التالي: views/site/say.php. عندما يتم إستدعاء الدالة [[yii\web\Controller::render()|render()]] من قبل ال action، فإنه سينظر للمسار على الشكل التالي: views/ControllerID/ViewName.php، بحيث يكون في مثالنا السابق ال ContollerID هو ال site وال viewName هو say.
ملاحظة: في الشيفرة البرمجية أعلاه، تكون ال message مضمنة داخل ال [[yii\helpers\Html::encode()]] قبل أن يتم طباعتها، هذا الأمر ضروري لأن ال parameter التي تأتي من المستخدم النهائي لا يجب الوثوق بها، فهي يمكن أن تحتوي على شيفرات برمجية تستغل الضعف الحاص بك بموضوع الأمان مثل vulnerable to XSS attack عن طريق دمج JS code مع ال parameter.
وبطبيعة الحال، يمكنك وضع المزيد من المحتوى في صفحة ال say view. ويمكن أن يتكون هذا المحتوى من HTML tag و plain text وحتى PHP statements.
في الواقع، تعد ال say view مجرد شيفرة برمجية بلغة ال PHP والتي يتم تنفيذها بواسطة [[yii\web\Controller::render()|render()]].
المحتوى الذي سيتم طباعته من خلال ال view سيتم إرجاعه الى التطبيق من خلال ال response، وسيقوم التطبيق بدوره بإخراج هذه النتيجة إلى المستخدم النهائي.
##
تطبيق المثال
-------------
بعد إنشاء ال action وصفحة ال view، يمكنك الوصول إلى الصفحة الجديدة عن طريق عنوان URL التالي:
سينتج عن هذا ال URL صفحة تعرض "Hello World". هذه الصفحة لديها نفس ال Header و ال Footer لصفحات التطبيق الأخرى.
إذا قمت بحذف ال message parameter من ال URL ، فسترى الصفحة تعرض كلمة " Hello " فقط. ويرجع ذلك إلى أن "message" يتم تمريرها ك parameter إلى ال actionSay()، وعندما يتم حذفها، سيتم استخدام القيمة الافتراضية وهي "Hello" بدلاً من ذلك.
معلومة: تتشارك الصفحة الجديدة مع الصفحات الأخرى بالتطبيق بنفس ال Header وال Footer وذلك بسبب الدالة [[yii\web\Controller::render() | render ()]] والتي ستقوم بشكل تلقائي بتضمين النتيجة الخاصة بصفحة ال view say مع صفحة ال Layout، والتي يمكنك أن تجدها داخل المسار التالي: views/layouts/main.php
ال r الموجودة في ال URL أعلاه يتطلب الكثير من الشرح. ولكن باختصار يمكن القوم أنها اختصار ل route ، وهو معرف فريد من نوعه(unique ID) للتطبيق بحيث يقوم بالتأشير على ال action، والصيغة الخاصة بال route هي ControllerID/ActionID. عندما يتلقى التطبيق request، فإنه سيتم التحقق من r parameter، فيقوم باستخدام الجزء ControllerID لتحديد ال controller class المطلوب ليقوم بعمل instance منه، ومن ثم يقوم ال controller باستخدام ال "ActionID" لتحديد ال action المطلوب والذي سيقوم بالعمل الفعلي.
في المثال الخاص بنا، فإن ال route هو "site/say"، وهذا ال route يتم معالجته ليستدعي ال controller class المسمى ب SiteController و ال action المسمى ب actionSay داخل هذا ال controller، ونتيجة لذلك سيتم فعليا إستدعاء الدالة SiteController::actionSay() لتقوم بمعالجة ال request كما يلزم.
معلومة: مثل ال actions، تحتوي ال controllers أيضًا على Uniquely IDs يتم تعريفها واستخدامها من خلال التطبيق. تستخدم ال Controllers IDs نفس قواعد التسمية الخاصة بال action IDs، ويتم ذلك من خلال حذف ال dashes و capitalizing أول حرف من كل كلمة، ثم إضافة كلمة Controller الى الإسم الناتج -وهنا الإختلاف عن ال action ID-. مثال: ال controller ID المسمى ب "post-comment" ستم معالجته ليصبح PostCommentController.
##
الخلاصة
في هذا الموضوع، قمنا بالتعرف على ال controller وال view كأجزاء من MVC architectural pattern، كما قمنا بإنشاء action داخل controller موجود ليستقبل specific request ويتحكم فيه، وقمنا أيضا بإنشاء view لعرض المحتوى. في هذا المثال البسيط، لم نتطرق الى ال model، وقمنا فقط باستخدام ال data بشكل مباشر من خلال ال message parameter.
كما تعرفنا أيضا على ال routes في ال Yii، والتي تعمل بدورها كجسر بين ال user request وال controller actions.
في الموضوع القادم، ستتعلم كيف يمكنك إنشاء model وكيف يمكنك إنشاء صفحة جديدة تحتوي على Html form.
---
### Guide Ar Start Installation (`docs/guide-ar/start-installation.md`)
#
تثبيت ال Yii
يمكنك تثبيت ال Yii بطريقتين ، الأولى باستخدام مدير الحزم Composer أو عن طريق تنزيل Archive File. الطريقة الأولى هي الطريقة المفضلة للعمل، ، لأنها تتيح لك تثبيت [extensions - ملحقات أو اضافات] جديدة، أو تحديث إطار العمل Yii ببساطة عن طريق تشغيل أمر واحد فقط.
التثبيت الإفتراضي لل Yii ينتج عنه بنية تركيبة منظمة ومرتبة للمجلدات والملفات التي بداخلها، ويوفر هذا الكلام بعض المميزات التي يتم إضافتها وإنشائها بشكل تلقائي مثل صفحة تسجيل الدخول، ونموذج اتصل بنا...الخ، هذا الأمر سيشكل نقطة إنطلاق جيدة لبدء العمل على أي مشروع.
في هذه الصفحة من التوثيق سنقوم بشرح ووصف كيف يمكن تثبيت إطار العمل Yii وبالتحديد Yii2 Basic Project Template.
هناك Template آخر موجود بإطار العمل Yii وهو Yii2 Advanced Project Template، وهو الأفضل للعمل وإنشاء المشاريع لفريق عمل برمجي، ولتطوير المشاريع متعددة الطبقات(multiple tires).
معلومة: قالب المشروع الأساسي (Basic) مناسب لتطوير 90% من تطبيقات الويب. ويختلف القالب المتقدم (Advanced Template) عن القالب الأساسي في كيفية تنظيم وهيكلة الشيفرة البرمجية.
اذا كنت جديدا في عالم تطوير تطبيقات الويب باستخدام ال Yii، فإننا نوصيك بقوة بأن تستخدم القالب الأساسي في بناء المشروع الخاص بك.
##
تثبيت ال Yii من خلال (Composer)
###
تثبيت ال Composer
إن لم يكن لديك Composer مثبت مسبقا، فيمكنك السير بخطوات تثبيته من خلال الدخول الى هذا الرابط https://getcomposer.org/download/.
لتثبيت ال Composer في كل من نظامي Linux و Max OS X، يمكنك تنفيذ الأوامر التالية:
في هذا الدليل ، نفترض أنك قمت بتثبيت ال composer على مستوى جميع المشاريع (globally) بحيث تكون أوامر ال composer متاحة لجميع المشاريع من أي مكان. أما إذا كنت تستخدم ال composer.phar لمسار محدد فقط(local directory)، فيجب عليك ضبط الأومر وفقًا لذلك.
إذا كان ال composer مثبتًا من قبل، فتأكد من استخدام إصدار حديث. يمكنك تحديث ال composer عن طريق تنفيذ الأمر التالي composer self-update
ملاحظة مهمة: أثناء تثبيت ال Yii ، سيحتاج ال composer إلى طلب(request) الكثير من المعلومات من ال Github Api. يعتمد عدد الطلبات على عدد dependencies التي يمتلكها التطبيق الخاص بك، وقد يكون هذا العدد أكبر من الحد المسموح به من قبل ال Github Api (Github API rate limit). إذا وصلت الى الحد الأعلى المسموح به من الطلبات، فقد يطلب منك ال composer بيانات تسجيل الدخول إلى Github، وذلك للحصول على رمز (token) للدخول إلى Github Api. اذا كانت عمليات الإتصال سريعة، فقد تصل إلى هذا الحد(limit) قبل أن يتمكن ال composer من التعامل معه ، لذالك نوصي بتكوين رمز الدخول(access token) قبل تثبيت ال Yii. يرجى الرجوع إلى التوثيق الخاص بال Composer والإطلاع على التعليمات الخاصة Github API tokens للحصول على الإرشادات اللازمة للقيام بذلك.
###
تثبيت ال Yii
من خلال ال Composer، يمكنك الآن تثبيت ال Yii من خلال تنفيذ سطر الأوامر التالي داخل أي مسار يمكن الوصول اليه من قبل الويب
سطر الأوامر السابق سيقوم بتثبيت أحدث نسخة مستقرة(stable) من إطار العمل Yii داخل مسار جديد اسمه basic، ويمكنك التعديل على سطر الأوامر السابق لتغيير اسم المشروع لأي اسم ترغب فيه.
معلومة: اذا واجهتك أي مشكلة عند تنفيذ السطر `composer create-project` فيمكنك الذهاب إلى قسم استكشاف الأخطاء في ال composer.
في معظم الأخطاء الشائعة، وعند حل المشكلة أو الخطأ، يمكنك إكمال التثبيت من خلال الدخول الى المسار `basic` ومن ثم تنفيذ الأمر التالي: `composer update`.
تلميح: اذا كنت ترغب بتثبيت أحدث نسخة خاصة بالمطورين من ال Yii، فيمكنك ذلك من خلال إضافة الخيار stability وذلك من خلال سطر الأوامر التالي:
ملاحظة: نسخة المطورين من ال Yii يجب أن يتم إستخدامها للمواقع الإلكترونية التي لن تصدر كنسخة نهائية للمستخدم(Not for production) لأن ذلك يمكن أن يسبب بإيقاف المشروع أو الشيفرة البرمجية الخاصة بك.
قم بفك ضغط الملف الذي تم تنزيله إلى مجلد يمكن الوصول إليه عبر الويب.
قم بتعديل ملف config/web.php عن طريق إدخال secret key ل cookieValidationKey
(يتم ذلك تلقائيًا إذا قمت بتثبيت ال Yii باستخدام Composer):
```php
// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
'cookieValidationKey' => 'enter your secret key here',
```
###
خيارات تثبيت أخرى
--------------------------
توضح تعليمات التثبيت أعلاه كيفية تثبيت ال Yii ، والذي يقوم أيضًا بإنشاء تطبيق ويب أساسي(basic).
هذا النهج هو نقطة انطلاق جيدة لمعظم المشاريع، صغيرة كانت أو كبيرة. خصوصا اذا كنت قد بدأت تعلم ال Yii من وقت قريب.
لكن، هناك خيارات أخرى متاحة لتثبيت ال Yii وهي:
إذا كنت ترغب فقط في تثبيت ال core لإطار العمل Yii، وترغب ببناء المكونات الخاصة بإطار العمل كما ترغب أنت وبطريقتك أنت، يمكنك اتباع التعليمات كما هو موضح في هذه الصفحة Building Application from Scratch.
إذا كنت تريد البدء بتطبيق أكثر تعقيدًا وأكثر إحترافية، ويتناسب بشكل أفضل مع وجود فريق عمل تقني،
فأنت اذا سترغب بتثبيت ال Advanced Project Template
###
تثبيت ال Assets
--------------------------
تعتمد ال Yii على حزم Bower و/أو NPM لتثبيت مكتبات ال (CSS و JavaScript). ويستخدم ال composer للحصول على هذه المكتبات ، مما يسمح بالحصول على إصدارات ال PHP و CSS/JavaScript في نفس الوقت. ويمكن تحقيق ذلك إما عن طريق استخدام asset-packagist.org أو من خلال ال composer asset plugin، يرجى الرجوع إلى Assets documentation لمزيد من التفاصيل.
قد ترغب في إدارة ال assets عبر ال native Bower/NPM أو استخدام ال CDN أو تجنب تثبيت ال assets بالكامل من حلال ال Composer ، ويمكن ذلك من خلال إضافة الأسطر التالية إلى "composer.json":
ملاحظة: في حالة تجاوز تثبيت ال assets عبر ال Composer، فأنت المسؤول عن تثبيت ال assets وحل مشكلات التعارض بين الإصدارات والمكتبات المختلفة. وكن مستعدًا لعدم تناسق محتمل بين ملفات ال asstes والإضافات المختلفة.
###
التحقق من التثبيت
--------------------------
بعد الانتهاء من التثبيت، ستحتاج الى القيام بإعداد خادم الويب الخاص بك(your web server) (انظر القسم التالي) أو قم باستخدام built-in PHP web server عن طريق تنفيذ الأمر التالي داخل المسار web في المشروع الخاص بك:
```bash
php yii serve
```
ملاحظة: افتراضيًا ال HTTP-server يعمل على البورت 8080. ومع ذلك ، إذا كان هذا البورت قيد الاستخدام بالفعل أو كنت ترغب في تشغيل أكثر من تطبيق بهذه الطريقة، حينها سيلزمك تحديد البورت الذي يجب استخدامه. ما عليك سوى إضافة --port:
```bash
php yii serve --port=8888
```
يمكنك استخدام الرابط الموجود في الأسفل للوصول الى تطبيق ال Yii الذي قمت بتثبيته وتنفيذ الأوامر السابقة عليه.
```
http://localhost:8080/
```
اذا كانت كل الإعدادات السابقة تعمل بشكل صحيح، فيجب أن ترى الصورة الموجودة بالأعلى "Congratulations!" على المتصفح. إذا لم يكن كذلك، يرجى التحقق مما إذا كان تثبيت الPHP الخاص بك متوافق مع متطلبات ال Yii. يمكنك التحقق من ذلك باستخدام أحد الأساليب التالية:
قم بنسخ الملف /requirements.php الى المسار /web/requirements.php بحيث يمكنك الوصول الى الصفحة من خلال الرابط التالي: http://localhost/requirements.php
قم بتنفيذ الأوامر التالية:
cd basic
php requirements.php
يجب عليك أن تقوم بتثبيت وإعداد ال PHP الخاص بك بحيث تلبي الحد الأدنى من متطلبات ال Yii. الأهم من ذلك يجب أن يكون الإصدار الخاص بال PHP أعلى أو يساوي 5.4. من الناحية المثالية أحدث إصدار يعمل مع ال Yii هو ال PHP 7. يجب عليك أيضًا تثبيت ال PDO PHP Extension.
###
إعداد ال Web Servers
-----------------------
معلومة: يمكنك تخطي هذا الجزء الآن إذا كنت تختبر فقط إطار العمل Yii دون أي نية لنشر هذا التطبيق على الويب(بدون رفع التطبيق على production server).
يجب أن يعمل التطبيق الذي تم تثبيته وفقًا للتعليمات المذكورة أعلاه مع أي من الخوادم ال Apache HTTP أو ال Nginx HTTP في كل من أنظمة التشغيل Windows, Mac OS X أو Linux ممن لديها إصدار أعلى أو يساوي PHP 5.4، كما أن ال Yii 2.0 متوافق مع ال Facebook HHVM، لكن، يجب أن تأخذ بعين الإعتبار أن ال HHVM يسلك في بعض الأحيان بطريقة مختلفة عن ال Native PHP، لذلك يجب أن تأخذ عناية إضافية عندما تعمل على ال HHVM.
على ال production server، قد ترغب في إعداد خادم الويب الخاص بك بحيث يمكن الوصول إلى التطبيق
الخاص بك عبر ال URL التالي https://www.example.com/index.php بدلاً من https://www.example.com/basic/web/index.php. هذا الكلام يتطلب إنشاء إعداد يقوم بتوجيه ال document root الموجود على ال web server الى مجلد ال basic/web، كما قد ترغب أيضا بإخفاء ال index.php من ال URL كما هو موضح في ال Routing and URL Creation. في هذا الموضوع ستتعلم كيف يمكنك إعداد ال Apache أو ال Nginx server لتحقيق هذه الأهداف.
معلومة: من خلال تعيين ال basic/web ك document root، فإنك بذلك تمنع أيضًا المستخدمين النهائيين من الوصول الى الشيفرة البرمجية الخاصة بالتطبيق الخاص بك، وتمنعهم من الوصول الى الملفات الحساسة والمهمة والمخزنة في sibling directories من basic/web، ويعبر رفض الوصول الى المجلدات الأخرى تحسينا أمنيا مهما، يساعد في الحفاظ على مستوى أعلى من الحماية.
معلومة: إذا كان سيتم تشغيل التطبيق الخاص بك في بيئة استضافة مشتركة(shared hosting) حيث ليس لديك الصلاحية لتعديل الإعدادات الخاصة بال web server، ستحتاج حينها الى تعديل في البنية الخاصة بالمشروع للحصول على أفضل أمان ممكن. يرجى الرجوع إلى Shared Hosting Environment لمزيد من المعلومات.
معلومة: إذا كنت تقوم بتشغيل تطبيق ال Yii بوجود ال proxy، فقد تحتاج إلى إعداد التطبيق ليكون ضمن ال trusted proxies and header.
###
الإعدادات الموصى بها لل Apache
-----------------------
استخدم الإعدادات التالية في ملف ال httpd.conf في Apache أو ضمن إعدادات ال virtual host.
ملاحظة: يجب عليك استبدال المسار التالي path/to/basic/web بالمسار الفعلي للتطبيق الخاص بك وصولا الى ال basic/web.
```apache
# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"
# use mod_rewrite for pretty URL support
RewriteEngine on
# If a directory or a file exists, use the request directly
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# Otherwise forward the request to index.php
RewriteRule . index.php
# if $showScriptName is false in UrlManager, do not allow accessing URLs with script name
RewriteRule ^index.php/ - [L,R=404]
# ...other settings...
```
###
الإعدادات الموصى بها لل Nginx
-----------------------
لاستخدام Nginx، يجب تثبيت PHP على أنه FPM SAPI، ويمكنك استخدام إعدادات ال Nginx التالية، مع الإنتباه على استبدال المسار من path/to/basic/web الى المسار الفعلي وصولا إلى basic/web بالإضافة الى إستبدال mysite.test إلى ال hostname الخاص بالتطبيق.
```nginx
server {
charset utf-8;
client_max_body_size 128M;
listen 80; ## listen for ipv4
#listen [::]:80 default_server ipv6only=on; ## listen for ipv6
server_name mysite.test;
root /path/to/basic/web;
index index.php;
access_log /path/to/basic/log/access.log;
error_log /path/to/basic/log/error.log;
location / {
# Redirect everything that isn't a real file to index.php
try_files $uri $uri/ /index.php$is_args$args;
}
# uncomment to avoid processing of calls to non-existing static files by Yii
#location ~ \.(js|css|png|jpg|gif|swf|ico|pdf|mov|fla|zip|rar)$ {
# try_files $uri =404;
#}
#error_page 404 /404.html;
# deny accessing php files for the /assets directory
location ~ ^/assets/.*\.php$ {
deny all;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/var/run/php5-fpm.sock;
try_files $uri =404;
}
location ~* /\. {
deny all;
}
}
```
عند استخدامك لهذا الإعداد، يجب عليك أيضًا تعيين cgi.fix_pathinfo = 0 في ملف php.ini
من أجل تجنب العديد من طلبات ال stat() الغير الضرورية للنظام.
لاحظ أيضًا أنه عند تشغيل خادم HTTPS، تحتاج إلى إضافة fastcgi_param HTTPS on;
بحيث يمكنك إكتشاف إذا ما كان الاتصال آمنًا أم لا.
---
### Guide Ar Start Looking Ahead (`docs/guide-ar/start-looking-ahead.md`)
#
ماذا الآن - الخطوة القادمة
إذا قمت بقرائة الفصل الخاص ب "البداية من هنا"، فأنت الآن قادر على بناء تطبيق Yii متكامل، لقد تعلمت كيف يمكنك تنفيذ وإستخدام أكثر الخصائص والمميزات المشتركة، مثل جلب البيانات من قاعدة البيانات، وأخذ البيانات من المستخدمين، ومن ثم عرضها، كما تعلمت كيف يمكنك تقسيم البيانات الى صفحات، وقمنا باستخدام ال Gii وتعلمنا كيف يمكننا إنشاء شيفرة برمجية من خلاله بشكل تلقائي، ومن الممارسة تعلمنا أن إنشاء الشيفرة البرمجية من خلال ال Gii يجعل من عملية تطوير المواقع والوظائف المطلوبة أمرا بسيطا وسهلا للغابة، كل ما عليك القيام به هو تعبئة ال forms.
في هذا الجزء من التوثيق سنعرض ملخص للمصادر المتاحة لل Yii، والتي ستساعدك في تحسين إنتاجيتك عند إستخدامك لبيئة العمل Yii.
التوثيق
The Definitive Guide - الدليل الشامل: كما يشير الإسم، فإن هذا الدليل يحدد آلية عمل ال Yii بدقة عالية، ويوفر إرشادات حول كيفية إستخدام ال Yii، هذا الجزء الأكثر أهمية في ال Yii، والذي يجب عليك قرائته قبل كتابة أي Yii code (ملاحظة: جزء البداية من هنا، والذي قمنا بدراسته هو أحد هذه الأجزاء، ومن أهمها للبدء بإنشاء التطبيقات من خلال ال Yii).
The Class Reference - المرجع الخاص بال Class في هذا الجزء يتم تحديد الية إستخدام كل Class يقدمه ال Yii، في العادة يتم إستخدام هذا المرجع عند كتابة شيفرة برمجية وأنت ترغب في فهم آلية العمل ل Class معين، أو Method, او فهم Proporty معينة...الخ، من الأفضل إستخدام المرجع الخاص بال Class فقط عند فهم آلية العمل لل Yii.
The Wiki Articles - مقالات الويكي مقالات الويكي هي مجموعة من الخبرات العملية للمستخدمين، تمت كتابتها ونشرها على شكل مقالات لمشاركة الخبرات، ومعظم هذه الكتابات تكون مثل الوصفات الخاصة بالطبخ، موجودة لخدمة هدف معين، وحل مشكلة محددة باستخدام ال Yii، وبالرغم من أن هذه الكتابات قد لا تكون بجودة ودقة الدليل الشامل، الا أنها قد تغطي مواضيع أكثر، وتطرح أيضا حلولا مباشرة للإستخدام.
Extensions - الملحقات: تفتخر ال Yii بوجود مكتبة ضخمة من الملحقات التي تمت برمجتها وإضافتها من قبل المستخدمين المتطوعين الذين شاركوا أعمالهم وطورها لتجعل مهمة المطورين الآخرين أسهل وأسرع في تطوير التطبيفات المبنية بواسطة ال Yii.
---
### Guide Ar Start Prerequisites (`docs/guide-ar/start-prerequisites.md`)
#
ماذا يجب أن تعرف قبل البدء بال Yii
منحنى التعلم الخاص بال Yii ليس حادًا مثل أطر PHP الأخرى، ولكن لا يزال هناك بعض الأشياء التي يجب أن تتعلمها قبل البدء بـال Yii.
##
PHP
ال Yii هو إطار عمل PHP، لذا تأكد من قراءة وفهم المرجع الرسمي الخاص بلغة ال PHP. عند البدء بتطوير المشاريع أو التطبيقات باستخدام ال Yii ، ستكتب التعليمات البرمجية بطريقة كائنية التوجه OOP، لذا تأكد من أنك على دراية بـمفاهيم ال OOP وكذلك ال namespaces.
##
البرمجة كائنية التوجه object oriented programming
كمبرمج أو مطور يرغب بالعمل على ال Yii، يجب عليك أن تمتلك المعرفة الأساسية للبرمجة كائنية التوجه OOP. إذا لم تكن على دراية بها ، فيمكنك تعلم ذلك من خلال واحدة من هذه الدورات المنتشرة مثل هذه الدورة من tuts+.
ملاحظة: كلما زاد تعقيد التطبيق أو المشروع الذي تعمل عليه، كلما احتجت الى مستوى أعلى وإحترافي أكثر من مفاهيم ال OOP لحل وإدارة التعقديات التي ستترب على مثل هذه المشاريع.
##
Command line and composer
تستخدم ال Yii بشكل كبير de-facto standard PHP package manager، ال Composer، لذلك تأكد من قرائتك وفهمك لهذا الموضوع قبل أن تبدء. بالإضافة الى ذلك إذا لم تكن على دراية باستخدام سطر الأوامر (command line) ، فقد حان الوقت لبدء المحاولة. بمجرد تعلم الأساسيات ، لن ترغب في العمل بدون إستخدام سطر الأوامر.
ال composer: ويترجم حرفيا الى كلمة "الملحن"، وهي عبارة عن أداة لإدارة المشاريع البرمجية والتي تسمح لك بتحديث وتنزيل المكتبات البرمجية المطلوبة للمشروع الخاص بك.
---
### Guide Ar Start Workflow (`docs/guide-ar/start-workflow.md`)
#
تشغيل التطبيقات
بعد تثبيت ال Yii، سيكون لديك تطبيق Yii جاهز للعمل عليه ويمكن الوصول إليه عبر
الرابط التالي: https://hostname/basic/web/index.php أو https://hostname/index.php إعتمادا على الإعدادات
الخاصة بك (إعدادت ال web server). في هذا الجزء سنستعرض الوظائف ال built-in الموجودة في التطبيق الإفتراضي لإطار العمل Yii، وكيف يقوم بتنظيم الشيفرة البرمجية، وكيف يعالج (handling) هذا التطبيق الطلبات (requests) بشكل عام.
معلومة: من أجل تبسيط الطرح، ومن خلال هذا البرنامج التعليمي " Getting Started - البداية من هنا"، من المفترض أنك قمت بتعيين basic/web ك document root لل Web server، وقد قمت أيضا بإعداد ال Url الذي يسمح لك بالوصول الى التطبيق المثبت من خلاله ليكون على الشكل التالي: https://hostname/index.php أو ما شابه ذلك.
اذا لم تقم بذلك، ولتلبية إحتياجاتك في هذا البرنامج التعليمي، يرجى ضبط ال Url كما هو موضح في هذه الصفحة.
يمكنك معرفة الضبط الخاص بال Web server من هنا: تثبيت ال Yii
ملاحظة: بخلاف إطار العمل نفسه(Yii framework)، بعد تثبيت ال template الخاص بالمشروع، يكون كل شيء في هذا التطبيق يخصك أنت، بحيث تملك الحرية في إضافة أو حذف أو تعديل كل ما تحتاج اليه.
##
خصائص / وظائف التطبيق المثبت - Functionality
يحتوي ال Basic ِApplication Template الذي قمنا بتثبيته على أربع صفحات:
الصفحة الرئيسية(Homepage): يتم عرض هذه الصفحة من خلال الرابط التالي https://hostname/index.php
صفحة من نحن(About)
صفحة اتصل بنا (Contact): في هذه الصفحة يتم عرض form يسمح للأعشاء بالإتصال بك من خلال البريد الإلكتروني.
صفحة تسجيل الدخول (Login): في هذه الصفحة يتم عرض form يسمح للأعضاء بالحصول على الإذن لإستخدام الخصائص التي لا يجوز لغيرهم من الوصول اليها، قم بتجربة تسجيل الدخول من خلال استخدام admin/admin ولاحظ أن كلمة "Login" ستختفي من القائمة الرئيسية وستظهر محلها الكلمة "Logout"
هذه الصفحات تشترك بامتلاكها common header and footer -الترويسة أعلى الصفحة، والذيل أسفل الصفحة-. ويحتوي ال header على القائمة الرئيسية (main menu) والتي بدورها تسمح لك بالتنقل بين الصفحات المختلفة.
أيضا، يجب عليك أن تنظر الى ال toolbar الموجود في أسفل نافذة المتصفح. ال debugger tool هذه تعتبر كأداة مفيدة مقدمة من ال Yii لتسجيل وعرض الكثير من المعلومات وتصحيح الأخطاء، مثل log messages, response statuses, the database queries run وما إلى ذلك.
بالإضافة إلى ال web application، يوجد هناك "console script" يسمى ب yii، والذي ستجده في المسار الرئيسي للتطبيق. هذا السكربت يمكن استخدامه لتشغيل المهام التي تعمل في الخفاء (background) أو لتنفيذ مهام الصيانة (ال maintenance). ستجد الوصف الخاص بهذا السكربت
داخل هذه الصفحة Console Application Section.
##
هيكلية التطبيق - Application Structure
أكثر المسارات والملفات أهمية الموجودة داخل التطبيق (بافتراض أن ال application's root directory هو basic) هي:
```
basic/ application base path
composer.json used by Composer, describes package information
config/ contains application and other configurations
console.php the console application configuration
web.php the Web application configuration
commands/ contains console command classes
controllers/ contains controller classes
models/ contains model classes
runtime/ contains files generated by Yii during runtime, such as logs and cache files
vendor/ contains the installed Composer packages, including the Yii framework itself
views/ contains view files
web/ application Web root, contains Web accessible files
assets/ contains published asset files (javascript and css) by Yii
index.php the entry (or bootstrap) script for the application
yii the Yii console command execution script
```
بشكل عام، يمكن تقسيم الملفات داخل التطبيق إلى نوعين: الاول تجده تحت المسار التالي: basic/web والثاني تجده بالمسارات الأخرى.
وبنائا على ذلك، فإنه من الممكن الوصول إلى النوع الأول مباشرة عبر ال HTTP (أي من خلال المتصفح) ، بينما لا يمكن أن يكون ذلك للنوع الثاني.
يعتمد ال Yii على إستخدام ال MVC، وال MVC هو أحد ال Architectural Pattern، وهي اختصار ل model-view-controller،
هذا الأسلوب ينعكس في تنظيم المسارات الخاصة بالملفات كما في الشكل أعلاه. يحتوي المسار models على جميع الكلاس (model classes) ، ويحتوي مسار ال views على جميع الصفحات التي ستستخدم في العرض (view scripts)، ويحتوي مسار الcontrollers على
جميع (controller classes)
يوضح المخطط التالي ال static structure للتطبيق.
يحتوي كل تطبيق على نص برمجي يستخدم للدخول الى التطبيق (كبوابة بعدها يظهر التطبيق للناظر)، ويسمى هذا الجزء بال entry script، وهو يمثل الصفحة web/index.php، ويعد هذا المدخل النص البرمجي الوحيد الذي يمكن الوصول إليه من خلال ال PHP في التطبيق، ويعمل هذا ال entry script على أخذ ال request ومن ثم إنشاء instance خاص بالتطبيق ليستطيع التعامل معه (التعامل مع التطبيق ومكوناته).
يقوم application على معالجة ال request بمساعدة من ال components، ومن ثم بقوم التطبيق بإرسال ال request الى عناصر ال MVC، كما يتم استخدام ال Widgets في ال views للمساعدة في إنشاء العناصر المعقدة والمتغيرة (Complex & Dynamic user interface) لواجهة المستخدم.
##
دورة الحياة الخاصة بال request
يوضح المخطط التالي كيفية معالجة التطبيق ل request معين.
يقوم المستخدم بعمل request لل entry scriptweb/index.php.
يقوم ال entry script على جلب الإعدادات الخاصة بالتطبيق ومن ثم إنشاء ال instance الخاص بالتطبيق ليستطيع التحكم ب request وإدارتها.
يقوم التطبيق على إنشاء instance من ال controller للتحكم بال request.
يقوم ال controller على إنشاء action instance مع مجموعة من الفلاتر(المرشحات) الخاصة بهذا ال action.
في حالة فشل أي فلتر، يتم إلغاء الإجراء.
في حال نجاح جميع الفلاتر ، يتم تنفيذ الإجراء.
يقوم ال action بجلب بعض البيانات الخاصة بال models, وفي الغالب ستكون من قاعدة البيانات إن أمكن ذلك.
سيقوم ال action بجلب ال view ليقوم بتقديم البيانات التي تم جلبها لل view.
عملية الجلب السابقة ستقوم على إرجاع النتائج الى response application component
بعد ذلك سيقوم ال response component بإرسال النتيجة النهائية الى المتصفح الخاص بالمستخدم.
---
### Guide De Blocktypes.Json (`docs/guide-de/blocktypes.json`)
{
"Warning:": "Achtung:",
"Note:": "Hinweis:",
"Info:": "Info:",
"Tip:": "Tipp:"
}
---
### Guide De Intro Yii (`docs/guide-de/intro-yii.md`)
Was ist Yii?
============
Yii ist ein leistungsstarkes, komponentenbasiertes PHP-Framework zur schnellen Entwicklung moderner Webanwendungen.
Der Name Yii (ausgesprochen `Ji` oder `[ji:]`) bedeutet im Chinesischen "einfach und evolutionär". Er kann außerdem
als Akronym für **Yes It Is!** (zu Deutsch **Ja, ist es!**) verstanden werden.
Wofür ist Yii am besten geeignet?
---------------------------------
Yii ist universell einsetzbar: Mit ihm lassen sich Webanwendungen aller Art entwickeln. Dank seiner komponentenbasierten
Architektur und seiner ausgefeilten Caching-Unterstützung eignet es sich besonders für umfangreiche Anwendungen wie
Portale, Foren, Content-Management-Systeme (CMS), E-Commerce-Projekte, RESTful Web Services und vieles mehr.
Wie unterscheidet sich Yii von anderen Frameworks?
--------------------------------------------------
Wenn Sie bereits mit einem anderen Framework vertraut sind, wird es Sie vermutlich interessieren, wie Yii im Vergleich
dazu abschneidet:
- Wie die meisten PHP-Frameworks implementiert Yii das Architekturmuster MVC (Model-View-Controller) und fördert eine
Organisation des Codes, die auf diesem Muster basiert.
- Yii vertritt die Philosophie, dass Code auf eine einfache und dennoch elegante Weise geschrieben werden sollte.
Yii wird nie versuchen, Strukturen zu verkomplizieren, nur um ein bestimmtes Entwurfsmuster strikt einzuhalten.
- Yii ist ein Full-Stack-Framework: Seine Komponenten decken alle Schichten einer Anwendung ab und bieten viele
bewährte und sofort einsatzbereite Funktionen, darunter Query Builder und ActiveRecord für relationale und
NoSQL-Datenbanken, Unterstützung für die Entwicklung von RESTful APIs, mehrstufiges Caching und mehr.
- Yii ist sehr gut erweiterbar. Sie können fast jeden Teil des Kerncodes anpassen oder ersetzen. Sie können außerdem
die solide Erweiterungsarchitektur von Yii nutzen, um weiterverteilbare Erweiterungen einzusetzen oder zu entwickeln.
- Hohe Performance ist immer ein vorrangiges Ziel von Yii.
Yii ist keine One-Man-Show, sondern wird von einem [starken Kern-Entwicklerteam](https://www.yiiframework.com/team/)
sowie einer [großen Community](https://github.com/yiisoft/yii2/graphs/contributors) von Fachleuten unterstützt, die
ständig zur Entwicklung von Yii beitragen. Das Yii-Entwicklerteam behält die neuesten Webentwicklungstrends sowie die
Best Practices und Funktionen im Auge, die in anderen Frameworks und Projekten zu finden sind. Die relevantesten
Best Practices und Funktionen, die anderswo zu finden sind, werden regelmäßig in das Kernframework integriert und über
einfache und elegante Schnittstellen zugänglich gemacht.
Yii-Versionen
-------------
Yii steht derzeit in zwei Major-Versionen zur Verfügung: 1.1 und 2.0. Version 1.1 ist die alte Generation und befindet
sich nun im Wartungsmodus. Version 2.0 ist eine komplette Neufassung von Yii, die die neuesten Technologien und
Protokolle aufgreift, einschließlich Composer, PSR, Namespaces, Traits usw. Version 2.0 ist die aktuelle Generation
des Frameworks und wird in den nächsten Jahren der Hauptfokus der Entwicklung sein.
In diesem Handbuch geht es hauptsächlich um die Version 2.0.
> Info: Mit Yii3 ist inzwischen auch die nächste Generation des Frameworks verfügbar. Sie wird in diesem Handbuch
> nicht behandelt. Weitere Informationen finden Sie im [Handbuch zu Yii3](https://yiisoft.github.io/docs/guide/).
Anforderungen und Voraussetzungen
---------------------------------
Yii 2.0 erfordert PHP 7.4.0 oder höher und läuft am besten mit der neuesten Version von PHP. Detailliertere
Informationen über die Anforderungen einzelner Funktionen erhalten Sie, indem Sie den "Requirement Checker" ausführen,
der in jedem Yii-Release enthalten ist.
Die Verwendung von Yii erfordert Grundkenntnisse in der objektorientierten Programmierung (OOP), da es sich bei Yii um
ein rein OOP-basiertes Framework handelt. Yii 2.0 nutzt auch die neuesten Funktionen von PHP, wie z. B.
[Namespaces](https://www.php.net/manual/de/language.namespaces.php) und
[Traits](https://www.php.net/manual/de/language.oop5.traits.php). Das Verständnis dieser Konzepte wird Ihnen helfen,
sich leichter in Yii 2.0 zurechtzufinden.
---
### Guide De Start Gii (`docs/guide-de/start-gii.md`)
Code generieren mit Gii
=======================
Dieser Abschnitt beschreibt, wie [Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) zur
automatischen Generierung von Code verwendet werden kann, der gängige Webseitenfunktionen abdeckt. Die Verwendung von
Gii erfordert nur die Eingabe der richtigen Informationen, wie auf den Gii-Seiten beschrieben.
In diesem Tutorial lernen Sie:
* die Aktivierung von Gii in Ihrer Anwendung
* die Verwendung von Gii zur Generierung einer Active-Record-Klasse
* die Verwendung von Gii zur Generierung des Codes zur Implementierung von CRUD-Operationen für eine Datenbanktabelle
* die individuelle Anpassung des Codes, der von Gii generiert wird
Gii starten
-----------
[Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) wird als [Modul](structure-modules.md) für Yii
angeboten. Sie können Gii durch die Konfiguration der [[yii\base\Application::modules|modules]]-Eigenschaft der
Anwendung aktivieren. Abhängig davon, wie Sie Ihre Anwendung aufgesetzt haben, finden Sie den folgenden Code
möglicherweise bereits in der Konfigurationsdatei `config/web.php`:
```php
$config = [ ... ];
if (YII_ENV_DEV) {
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = [
'class' => 'yii\gii\Module',
];
}
```
Die obenstehende Konfiguration legt fest, dass die Anwendung in der
[Entwicklungsumgebung](concept-configurations.md#environment-constants) ein Modul mit dem Namen `gii` lädt, das durch
die Klasse [[yii\gii\Module]] abgebildet wird.
Prüfen Sie das [Einstiegsskript](structure-entry-scripts.md) `web/index.php` Ihrer Anwendung. Dort finden Sie die
folgende Zeile, die im Wesentlichen bewirkt, dass `YII_ENV_DEV` den Wert `true` hat:
```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```
Aufgrund dieser Zeile befindet sich Ihre Anwendung im Entwicklungsmodus. Dadurch ist sichergestellt, dass Gii mittels
obenstehender Konfiguration aktiviert wird. Sie können nun mittels folgender URL darauf zugreifen:
```
https://hostname/index.php?r=gii
```
> Note: Falls Sie von einem anderen Computer als `localhost` auf Gii zugreifen, wird Ihnen der Zugriff aus
> Sicherheitsgründen standardmäßig verweigert. Fügen Sie Ihre IP-Adresse wie folgt zu den `allowedIPs` hinzu, um den
> Zugriff zu erlauben:
>
```php
'gii' => [
'class' => 'yii\gii\Module',
'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'] // Passen Sie dies an Ihre Bedürfnisse an
],
```
Generieren einer Active-Record-Klasse
-------------------------------------
Um mittels Gii eine Active-Record-Klasse zu generieren, klicken Sie auf den "Model Generator"-Link auf der Startseite
von Gii. Füllen Sie das Formular daraufhin wie folgt aus:
* Table Name: `country`
* Model Class: `Country`
Klicken Sie dann auf den "Preview"-Button. Daraufhin sehen Sie in der Ergebnisliste die zu erstellende Datei
`models/Country.php`. Klicken Sie auf den Dateinamen, um sich eine Vorschau des Inhalts der Datei anzusehen.
Wenn bereits eine Datei mit demselben Namen existiert und Sie diese überschreiben würden, können Sie vorher auf den
`diff`-Button neben dem Dateinamen klicken, um sich die Unterschiede zwischen dem zu generierenden Code und der
bestehenden Version anzusehen.
Zum Überschreiben einer existierenden Datei aktivieren Sie die Checkbox neben "overwrite" und klicken Sie dann auf den
"Generate"-Button. Beim Generieren einer neuen Datei können Sie einfach auf den "Generate"-Button klicken.
Daraufhin erscheint eine Seite, die Ihnen bestätigt, dass der Code erfolgreich generiert wurde. Falls die Datei bereits
existierte, erscheint zusätzlich eine Meldung, dass diese mit dem neu generierten Code überschrieben wurde.
Generieren von CRUD-Code
------------------------
CRUD steht für Create, Read, Update und Delete. Dies sind die englischen Begriffe für die vier Standardaufgaben in der
Datenverarbeitung der meisten Webseiten. Um mittels Gii Code mit CRUD-Funktionalität zu generieren, klicken Sie auf
"CRUD Generator" auf der Startseite von Gii. Im "country"-Beispiel füllen Sie das Formular wie folgt aus:
* Model Class: `app\models\Country`
* Search Model Class: `app\models\CountrySearch`
* Controller Class: `app\controllers\CountryController`
Klicken Sie dann auf den "Preview"-Button. Daraufhin sehen Sie eine Liste der zu generierenden Dateien (siehe Bild
unten).
Falls Sie zuvor den Controller `controllers/CountryController.php` und die Datei `views/country/index.php` erstellt
haben (im Datenbank-Abschnitt des Handbuchs), aktivieren Sie die Checkboxen "overwrite", um die beiden Dateien zu
ersetzen (die bisherigen Versionen bieten keine vollständige CRUD-Unterstützung).
Probieren Sie es aus
--------------------
Um die generierten Dateien in Aktion zu sehen, navigieren Sie in Ihrem Browser zu folgender URL:
```
https://hostname/index.php?r=country%2Findex
```
Sie sehen hier eine Datentabelle, die Ihnen die Länder aus der Datenbanktabelle anzeigt. Sie können die Daten sortieren
oder durch die Eingabe von Filterbedingungen im Tabellenkopf filtern.
Für jedes Land in der Tabelle gibt es rechts Aktionslinks zum Anzeigen der Details, zum Bearbeiten oder zum Löschen des
Datensatzes. Sie können auch auf den "Create Country"-Button oberhalb der Tabelle klicken, um ein Formular zum Anlegen
eines neuen Landes zu öffnen.
Für den Fall, dass Sie die Dateien analysieren oder verändern möchten, finden Sie nachfolgend eine Liste der Dateien,
die von Gii generiert wurden:
* Controller: `controllers/CountryController.php`
* Models: `models/Country.php` und `models/CountrySearch.php`
* Views: `views/country/*.php`
> Info: Gii ist so aufgebaut, dass es einfach angepasst und erweitert werden kann. Durch kluges Einsetzen von Gii
> kann sich Ihr Entwicklungsprozess drastisch verkürzen. Weitere Informationen finden Sie im Abschnitt
> [Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide).
Zusammenfassung
---------------
In diesem Abschnitt haben Sie gelernt, wie man mit Gii Code generieren kann, der die vollständige CRUD-Funktionalität
für die in einer Datenbanktabelle gespeicherten Inhalte implementiert.
---
### Guide De Start Looking Ahead (`docs/guide-de/start-looking-ahead.md`)
Ausblick
========
Wenn Sie sich durch das gesamte "Einstieg"-Kapitel durchgearbeitet haben, haben Sie nun eine fertige Yii-Anwendung
erstellt. Dabei haben Sie gelernt, häufig benötigte Funktionen wie z. B. das Erfassen von Benutzerdaten mittels
HTML-Formularen, das Lesen von Daten aus einer Datenbank und deren seitenweise Darstellung umzusetzen. Sie wissen jetzt
auch, wie man mittels [Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) automatisch Code
generieren kann. Die Verwendung von Gii zur Code-Generierung macht einen Großteil Ihres Webentwicklungsprozesses so
einfach wie das Ausfüllen einiger Formulare.
Dieser Abschnitt fasst die verfügbaren Yii-Ressourcen zusammen, die Ihnen helfen, bei der Verwendung des Frameworks
produktiver zu sein.
* Dokumentation
- [Das umfassende Handbuch](https://www.yiiframework.com/doc-2.0/guide-README.html):
Wie der Name vermuten lässt, definiert dieses Handbuch genau, wie Yii funktionieren soll, und bietet eine
allgemeine Anleitung zur Verwendung von Yii. Es ist das wichtigste Yii-Tutorial, und Sie sollten es lesen, bevor
Sie Yii-Code schreiben.
- [Die Klassenreferenz](https://www.yiiframework.com/doc-2.0/index.html):
Hier finden Sie die Dokumentation aller Klassen, die von Yii bereitgestellt werden. Sie kommt hauptsächlich dann
zur Anwendung, wenn Sie beim Programmieren die Verwendung bestimmter Klassen, Methoden oder Eigenschaften
verstehen möchten. Die Verwendung dieser Dokumentation empfiehlt sich erst, wenn Sie ein Kontextverständnis des
gesamten Frameworks entwickelt haben.
- [Die Wiki-Artikel](https://www.yiiframework.com/wiki/?tag=yii2):
Die Wiki-Artikel wurden von Yii-Benutzern auf Basis ihrer eigenen Erfahrungen geschrieben. Die meisten dieser
Artikel sind im Stile von "Kochrezepten" verfasst und demonstrieren damit exemplarisch die Lösung eines
spezifischen Problems mittels Yii. Während die Qualität dieser Artikel unter Umständen die des Handbuchs nicht
erreicht, sind sie insofern nützlich, als sie ein breiteres Themenspektrum abdecken und oftmals
"Ready-to-use"-Lösungen anbieten.
- [Bücher](https://www.yiiframework.com/books)
* [Erweiterungen](https://www.yiiframework.com/extensions/):
Yii bietet eine Bibliothek mit tausenden Erweiterungen, die von Yii-Benutzern beigesteuert wurden und einfach in Ihre
Anwendungen integriert werden können. Damit lässt sich Ihr Entwicklungsprozess weiter beschleunigen und vereinfachen.
* Gemeinschaft
- Forum:
- IRC-Chat: Der #yii-Channel im Libera-Netzwerk ()
- Slack-Channel:
- Gitter-Chat:
- GitHub:
- Facebook:
- Twitter:
- LinkedIn:
- Stackoverflow:
---
### Guide Es Blocktypes.Json (`docs/guide-es/blocktypes.json`)
{
"Warning:": "Aviso:",
"Note:": "Nota:",
"Info:": "Información:",
"Tip:": "Consejo:"
}
---
### Guide Es Caching Data (`docs/guide-es/caching-data.md`)
Almacenamiento de Datos en Caché
================================
El almacenamiento de datos en caché trata del almacenamiento de alguna variable PHP en caché y recuperarla más tarde del mismo. También es la base de algunas de las características avanzadas de almacenamiento en caché, tales como [el almacenamiento en caché de consultas a la base de datos](#query-caching) y [el almacenamiento en caché de contenido](caching-page.md).
El siguiente código muestra el típico patrón de uso para el almacenamiento en caché, donde la variable `$cache` se refiere al [componente caché](#cache-components):
```php
// intenta recuperar $data de la caché
$data = $cache->get($key);
if ($data === false) {
// $data no ha sido encontrada en la caché, calcularla desde cero
// guardar $data en caché para así recuperarla la próxima vez
$cache->set($key, $data);
}
// $data está disponible aquí
```
## Componentes de Caché
El almacenamiento de datos en caché depende de los llamados *cache components* (componentes de caché) los cuales
representan diferentes tipos de almacenamiento en caché, como por ejemplo en memoria, en archivos o en base de datos.
Los Componentes de Caché están normalmente registrados como [componentes de la aplicación](structure-application-components.md) para que de esta forma puedan
ser configurados y accesibles globalmente. El siguiente código muestra cómo configurar el componente de aplicación
`cache` para usar [memcached](https://memcached.org/) con dos servidores caché:
```php
'components' => [
'cache' => [
'class' => 'yii\caching\MemCache',
'servers' => [
[
'host' => 'server1',
'port' => 11211,
'weight' => 100,
],
[
'host' => 'server2',
'port' => 11211,
'weight' => 50,
],
],
],
],
```
Puedes acceder al componente de caché usando la expresión `Yii::$app->cache`.
Debido a que todos los componentes de caché soportan el mismo conjunto de APIs, podrías cambiar el componente de caché
subyacente por otro diferente mediante su reconfiguración en la configuración de la aplicación sin tener que modificar
el código que utiliza la caché. Por ejemplo, podrías modificar la configuración anterior para usar [[yii\caching\ApcCache|APC cache]]:
```php
'components' => [
'cache' => [
'class' => 'yii\caching\ApcCache',
],
],
```
> Tip: Puedes registrar múltiples componentes de aplicación de caché. El componente llamado `cache` es usado por defecto por muchas clases caché-dependiente (ej. [[yii\web\UrlManager]]).
### Almacenamientos de Caché Soportados
Yii proporciona varios componentes de caché que pueden almacenar datos en diferentes medios. A continuación
se muestra un listado con los componentes de caché disponibles:
* [[yii\caching\ApcCache]]: utiliza la extensión de PHP [APC](https://www.php.net/manual/es/book.apc.php). Esta opción puede ser considerada como la más rápida de entre todas las disponibles para una aplicación centralizada. (ej. un servidor, no dedicado al balance de carga, etc).
* [[yii\caching\DbCache]]: utiliza una tabla de base de datos para almacenar los datos. Por defecto, se creará y usará como base de datos [SQLite3](https://sqlite.org/) en el directorio runtime. Se puede especificar explícitamente que base de datos va a ser utilizada configurando la propiedad `db`.
* [[yii\caching\DummyCache]]: dummy cache (caché tonta) que no almacena en caché nada. El propósito de este componente es simplificar el código necesario para chequear la disponibilidad de caché. Por ejemplo, durante el desarrollo o si el servidor no tiene soporte de caché actualmente, puede utilizarse este componente de caché. Cuando este disponible un soporte en caché, puede cambiarse el componente correspondiente. En ambos casos, puede utilizarse el mismo código `Yii::$app->cache->get($key)` para recuperar un dato sin la preocupación de que `Yii::$app->cache` pueda ser `null`.
* [[yii\caching\FileCache]]: utiliza un fichero estándar para almacenar los datos. Esto es adecuado para almacenar grandes bloques de datos (como páginas).
* [[yii\caching\MemCache]]: utiliza las extensiones de PHP [memcache](https://www.php.net/manual/es/book.memcache.php) y [memcached](https://www.php.net/manual/es/book.memcached.php). Esta opción puede ser considerada como la más rápida cuando la caché es manejada en una aplicación distribuida (ej. con varios servidores, con balance de carga, etc..)
* [[yii\redis\Cache]]: implementa un componente de caché basado en [Redis](https://redis.io/) que almacenan pares clave-valor (requiere la versión 2.6.12 de redis).
* [[yii\caching\WinCache]]: utiliza la extensión de PHP [WinCache](https://iis.net/downloads/microsoft/wincache-extension) ([ver también](https://www.php.net/manual/es/book.wincache.php)).
> Tip: Puedes utilizar diferentes tipos de almacenamiento de caché en la misma aplicación. Una estrategia común es la de usar almacenamiento de caché en memoria para almacenar datos que son pequeños pero que son utilizados constantemente (ej. datos estadísticos), y utilizar el almacenamiento de caché en archivos o en base de datos para guardar datos que son grandes y utilizados con menor frecuencia (ej. contenido de página).
## API de Caché
Todos los componentes de almacenamiento de caché provienen de la misma clase "padre" [[yii\caching\Cache]] y por lo tanto soportan la siguiente API:
* [[yii\caching\Cache::get()|get()]]: recupera un elemento de datos de la memoria caché con una clave especificada.
Un valor nulo será devuelto si el elemento de datos no ha sido encontrado en la memoria caché o si ha expirado o ha sido invalidado.
* [[yii\caching\Cache::set()|set()]]: almacena un elemento de datos identificado por una clave en la memoria caché.
* [[yii\caching\Cache::add()|add()]]: almacena un elemento de datos identificado por una clave en la memoria caché si la clave no se encuentra en la memoria caché.
* [[yii\caching\Cache::mget()|mget()]]: recupera varios elementos de datos de la memoria caché con las claves especificadas.
* [[yii\caching\Cache::mset()|mset()]]: almacena múltiples elementos de datos en la memoria caché. Cada elemento se identifica por una clave.
* [[yii\caching\Cache::madd()|madd()]]: almacena múltiples elementos de datos en la memoria caché. Cada elemento se identifica con una clave. Si una clave ya existe en la caché, el elemento será omitido.
* [[yii\caching\Cache::exists()|exists()]]: devuelve un valor que indica si la clave especificada se encuentra en la memoria caché.
* [[yii\caching\Cache::delete()|delete()]]: elimina un elemento de datos identificado por una clave de la caché.
* [[yii\caching\Cache::flush()|flush()]]: elimina todos los elementos de datos de la cache.
> Note: No Almacenes el valor boolean `false` en caché directamente porque el método [[yii\caching\Cache::get()|get()]] devuelve
el valor `false` para indicar que el dato no ha sido encontrado en la caché. Puedes poner `false` dentro de un array y cachear
este array para evitar este problema.
Algunos sistemas de almacenamiento de caché, como por ejemplo MemCache, APC, pueden recuperar múltiples valores almacenados en modo de lote (batch), lo que puede reducir considerablemente la sobrecarga que implica la recuperación de datos almacenados en la caché. Las API [[yii\caching\Cache::mget()|mget()]] y [[yii\caching\Cache::madd()|madd()]]
se proporcionan para utilizar esta característica. En el caso de que el sistema de memoria caché no lo soportara, ésta sería simulada.
Puesto que [[yii\caching\Cache]] implementa `ArrayAccess`, un componente de caché puede ser usado como un array.
El siguiente código muestra unos ejemplos:
```php
$cache['var1'] = $value1; // equivalente a: $cache->set('var1', $value1);
$value2 = $cache['var2']; // equivalente a: $value2 = $cache->get('var2');
```
### Claves de Caché
Cada elemento de datos almacenado en caché se identifica por una clave. Cuando se almacena un elemento de datos en la memoria caché, se debe especificar una clave. Más tarde, cuando se recupera el elemento de datos de la memoria caché, se debe proporcionar la clave correspondiente.
Puedes utilizar una cadena o un valor arbitrario como una clave de caché. Cuando una clave no es una cadena de texto, ésta será automáticamente serializada en una cadena.
Una estrategia común para definir una clave de caché es incluir en ella todos los factores determinantes en términos de un array. Por ejemplo, [[yii\db\Schema]] utiliza la siguiente clave para almacenar en caché la información del esquema de una tabla de base de datos:
```php
[
__CLASS__, // nombre de la clase del esquema
$this->db->dsn, // nombre del origen de datos de la conexión BD
$this->db->username, // usuario para la conexión BD
$name, // nombre de la tabla
];
```
Como puedes ver, la clave incluye toda la información necesaria para especificar de una forma exclusiva una tabla de base de datos.
Cuando en un mismo almacenamiento en caché es utilizado por diferentes aplicaciones, se debería especificar un prefijo único para las claves de la caché por cada una de las aplicaciones para así evitar conflictos. Esto puede hacerse mediante la configuración de la propiedad [[yii\caching\Cache::keyPrefix]]. Por ejemplo, en la configuración de la aplicación podrías escribir el siguiente código:
```php
'components' => [
'cache' => [
'class' => 'yii\caching\ApcCache',
'keyPrefix' => 'myapp', // un prefijo de clave de caché único
],
],
```
Para garantizar la interoperabilidad, deberían utilizarse sólo caracteres alfanuméricos.
### Caducidad de Caché
Un elemento de datos almacenado en la memoria caché permanecerá en ella para siempre, a menos que sea removida de alguna manera debido a alguna directiva de caché (ej. el espacio de almacenamiento en caché está lleno y los datos más antiguos se eliminan). Para cambiar este comportamiento, podrías proporcionar un parámetro de caducidad al llamar [[yii\caching\Cache::set()|set()]] para guardar el elemento de datos. El parámetro nos indica por cuántos segundos el elemento se mantendrá válido en memoria caché. Cuando llames [[yii\caching\Cache::get()|get()]] para recuperar el elemento, si el tiempo de caducidad ha pasado, el método devolverá `false`, indicando que el elemento de datos no ha sido encontrado en la memoria caché. Por ejemplo,
```php
// guardar los datos en memoria caché al menos 45 segundos
$cache->set($key, $data, 45);
sleep(50);
$data = $cache->get($key);
if ($data === false) {
// $data ha caducado o no ha sido encontrado en la memoria caché
}
```
### Dependencias de Caché
Además de configurar el tiempo de caducidad, los datos almacenados en caché pueden también ser invalidados conforme a algunos cambios en la caché de dependencias. Por ejemplo, [[yii\caching\FileDependency]] representa la dependencia del tiempo de modificación del archivo. Cuando esta dependencia cambia, significa que el archivo correspondiente ha cambiado. Como resultado, cualquier contenido anticuado que sea encontrado en la caché debería ser invalidado y la llamada a [[yii\caching\Cache::get()|get()]] debería retornar falso.
Una dependencia es representada como una instancia de [[yii\caching\Dependency]] o su clase hija. Cuando llamas [[yii\caching\Cache::set()|set()]] para almacenar un elemento de datos en la caché, puedes pasar el objeto de dependencia asociado. Por ejemplo,
```php
// Crear una dependencia sobre el tiempo de modificación del archivo example.txt.
$dependency = new \yii\caching\FileDependency(['fileName' => 'example.txt']);
// Los datos expirarán en 30 segundos.
// También podría ser invalidada antes si example.txt es modificado.
$cache->set($key, $data, 30, $dependency);
// La caché comprobará si los datos han expirado.
// También comprobará si la dependencia ha cambiado.
// Devolverá `false` si se encuentran algunas de esas condiciones.
$data = $cache->get($key);
```
Aquí abajo se muestra un sumario de las dependencias disponibles:
- [[yii\caching\ChainedDependency]]: la dependencia cambia si cualquiera de las dependencias en la cadena cambia.
- [[yii\caching\DbDependency]]: la dependencia cambia si el resultado de la consulta de la sentencia SQL especificada cambia.
- [[yii\caching\ExpressionDependency]]: la dependencia cambia si el resultado de la expresión de PHP especificada cambia.
- [[yii\caching\CallbackDependency]]: la dipendenza viene modificata se il risultato della callback PHP specificata cambia.
- [[yii\caching\FileDependency]]: la dependencia cambia si se modifica la última fecha de modificación del archivo.
- [[yii\caching\TagDependency]]: marca un elemento de datos en caché con un nombre de grupo. Puedes invalidar los elementos de datos almacenados en caché
con el mismo nombre del grupo a la vez llamando a [[yii\caching\TagDependency::invalidate()]].
## Consultas en Caché
Las consultas en caché es una característica especial de caché construido sobre el almacenamiento de caché de datos. Se
proporciona para almacenar en caché el resultado de consultas a la base de datos.
Las consultas en caché requieren una [[yii\db\Connection|DB connection]] y un componente de aplicación caché válido. El uso básico de las consultas en memoria caché es el siguiente, asumiendo que `db` es una instancia de [[yii\db\Connection]]:
```php
$result = $db->cache(function ($db) {
// el resultado de la consulta SQL será servida de la caché
// si el cacheo de consultas está habilitado y el resultado de la consulta se encuentra en la caché
return $db->createCommand('SELECT * FROM customer WHERE id=1')->queryOne();
});
```
El cacheo de consultas puede ser usado tanto para [DAO](db-dao.md) como para [ActiveRecord](db-active-record.md):
```php
$result = Customer::getDb()->cache(function ($db) {
return Customer::find()->where(['id' => 1])->one();
});
```
> Note: Algunos DBMS (ej. [MySQL](https://dev.mysql.com/doc/refman/5.6/en/query-cache.html)) también soporta el almacenamiento en caché desde el mismo servidor de la BD. Puedes optar por utilizar cualquiera de los mecanismos de memoria caché. El almacenamiento en caché de consultas previamente descrito tiene la ventaja que de que se puede especificar dependencias de caché de una forma flexible y son potencialmente mucho más eficientes.
### Configuraciones
Las consultas en caché tienen tres opciones configurables globales a través de [[yii\db\Connection]]:
* [[yii\db\Connection::enableQueryCache|enableQueryCache]]: activa o desactiva el cacheo de consultas.
Por defecto es `true`. Tenga en cuenta que para activar el cacheo de consultas, también necesitas tener una caché válida, especificada por [[yii\db\Connection::queryCache|queryCache]].
* [[yii\db\Connection::queryCacheDuration|queryCacheDuration]]: representa el número de segundos que un resultado de la consulta permanecerá válida en la memoria caché. Puedes usar 0 para indicar que el resultado de la consulta debe permanecer en la caché para siempre. Esta propiedad es el valor usado por defecto cuando [[yii\db\Connection::cache()]] es llamada sin especificar una duración.
* [[yii\db\Connection::queryCache|queryCache]]: representa el ID del componente de aplicación de caché.
Por defecto es `'cache'`. El almacenamiento en caché de consultas se habilita sólo si hay un componente de la aplicación de caché válida.
### Usos
Puedes usar [[yii\db\Connection::cache()]] si tienes multiples consultas SQL que necesitas a aprovechar el cacheo de consultas. El uso es de la siguiente manera,
```php
$duration = 60; // resultado de la consulta de caché durante 60 segundos.
$dependency = ...; // dependencia opcional
$result = $db->cache(function ($db) {
// ... realiza consultas SQL aquí ...
return $result;
}, $duration, $dependency);
```
Cualquier consulta SQL en una función anónima será cacheada durante el tiempo indicado con la dependencia especificada.
Si el resultado de la consulta se encuentra válida en la caché, la consulta se omitirá y el resultado se servirá de la caché en su lugar. Si no especificar el parámetro `$duration`, el valor [[yii\db\Connection::queryCacheDuration|queryCacheDuration]] será usado en su lugar.
A veces dentro de `cache()`, puedes querer desactivar el cacheo de consultas para algunas consultas especificas. Puedes usar [[yii\db\Connection::noCache()]] en este caso.
```php
$result = $db->cache(function ($db) {
// consultas SQL que usan el cacheo de consultas
$db->noCache(function ($db) {
// consultas SQL que no usan el cacheo de consultas
});
// ...
return $result;
});
```
Si lo deseas puedes usar el cacheo de consultas para una simple consulta, puedes llamar a [[yii\db\Command::cache()]] cuando construyas el comando. Por ejemplo,
```php
// usa el cacheo de consultas y asigna la duración de la consulta de caché por 60 segundos
$customer = $db->createCommand('SELECT * FROM customer WHERE id=1')->cache(60)->queryOne();
```
También puedes usar [[yii\db\Command::noCache()]] para desactivar el cacheo de consultas de un simple comando. Por ejemplo,
```php
$result = $db->cache(function ($db) {
// consultas SQL que usan cacheo de consultas
// no usa cacheo de consultas para este comando
$customer = $db->createCommand('SELECT * FROM customer WHERE id=1')->noCache()->queryOne();
// ...
return $result;
});
```
### Limitaciones
El almacenamiento en caché de consultas no funciona con los resultados de consulta que contienen controladores de recursos.
Por ejemplo, cuando se utiliza el tipo de columna `BLOB` en algunos DBMS, el resultado de la consulta devolverá un recurso para manejar los datos de la columna.
Algunos sistemas de almacenamiento caché tienen limitación de tamaño. Por ejemplo, memcache limita el tamaño máximo de cada entrada a 1MB. Por lo tanto, si el tamaño de un resultado de la consulta excede ese límite, el almacenamiento en caché fallará.
---
### Guide Es Caching Fragment (`docs/guide-es/caching-fragment.md`)
Caché de Fragmentos
===================
La Caché de Fragmentos se refiere al almacenamiento en caché de un fragmento, o sección, de una página Web. Por ejemplo, si
una página muestra un sumario de las ventas anuales en una tabla, podrías guardar esta tabla en memoria caché para
eliminar el tiempo necesario para generar esta tabla en cada petición (request). La caché de fragmentos está construido
sobre la [caché de datos](caching-data.md).
Para usar la caché de fragmentos, utiliza el siguiente código en tu [vista (view)](structure-views.md):
```php
if ($this->beginCache($id)) {
// ... generar contenido aquí ...
$this->endCache();
}
```
Es decir, encierra la lógica de la generación del contenido entre las llamadas [[yii\base\View::beginCache()|beginCache()]] y
[[yii\base\View::endCache()|endCache()]]. Si el contenido se encuentra en la memoria caché, [[yii\base\View::beginCache()|beginCache()]]
mostrará el contenido y devolverá `false`, saltandose así la lógica de generación del contenido. De lo contrario, el
código de generación se ejecutaría y al alcanzar la llamada [[yii\base\View::endCache()|endCache()]], el contenido
generado será capturado y almacenado en la memoria caché.
Como en la [caché de datos](caching-data.md), un `$id` (clave) único es necesario para identificar un contenido guardado en
caché.
## Opciones de Caché
Puedes especificar opciones adicionales para la caché de fragmentos pasando el array de opciones como segundo
parametro del método [[yii\base\View::beginCache()|beginCache()]]. Entre bastidores, este array de opciones se utiliza
para configurar el widget [[yii\widgets\FragmentCache]] que es en realidad el que implementa la funcionalidad de la caché
de fragmentos.
### Duración
Quizás la opción más utilizada en la caché de fragmentos es [[yii\widgets\FragmentCache::duration|duración]]. Ésta
especifica cuántos segundos el contenido puede permanecer como válido en la memoria caché. El siguiente código almacena
en la caché el fragmento de contenido para una hora a lo sumo:
```php
if ($this->beginCache($id, ['duration' => 3600])) {
// ... generar contenido aquí ...
$this->endCache();
}
```
Si la opción no está activada, se tomará el valor por defecto 60, lo que significa que el contenido almacenado en caché expirará en 60 segundos.
### Dependencias
Como en la [caché de datos](caching-data.md#cache-dependencies), el fragmento de contenido que está siendo almacenado en caché
también puede tener dependencias. Por ejemplo, el contenido de un artículo que se muestre depende de si el mensaje se
modifica o no.
Para especificar una dependencia, activa la opción [[yii\widgets\FragmentCache::dependency|dependencia]] (dependency),
que puede ser un objecto [[yii\caching\Dependency]] o un array de configuración para crear un objecto `Dependency`. El
siguiente código especifica que la caché de fragmento depende del cambio del valor de la columna `updated_at`:
```php
$dependency = [
'class' => 'yii\caching\DbDependency',
'sql' => 'SELECT MAX(updated_at) FROM post',
];
if ($this->beginCache($id, ['dependency' => $dependency])) {
// ... generar contenido aquí ...
$this->endCache();
}
```
### Variaciones
El contenido almacenado en caché puede variar de acuerdo a ciertos parámetros. Por ejemplo, para una aplicación Web que
soporte multiples idiomas, la misma pieza del código de la vista puede generar el contenido almacenado en caché
en diferentes idiomas. Por lo tanto, es posible que desees hacer variaciones del mismo contenido almacenado en caché de
acuerdo con la actual selección del idioma en la aplicación.
Para especificar variaciones en la memoria caché, configura la opción [[yii\widgets\FragmentCache::variations|variaciones]]
(variations), la cual deberá ser un array de valores escalares, cada uno de ellos representando un factor de variación.
Por ejemplo, para hacer que el contenido almacenado en la caché varíe por lenguaje, podrías usar el siguiente código:
```php
if ($this->beginCache($id, ['variations' => [Yii::$app->language]])) {
// ... generar código aquí ...
$this->endCache();
}
```
### Alternando el Almacenamiento en Caché
Puede que a veces quieras habilitar la caché de fragmentos únicamente cuando ciertas condiciones se cumplan. Por ejemplo,
para una página que muestra un formulario, tal vez quieras guardarlo en la caché cuando es inicialmente solicitado (a
través de una petición GET). Cualquier muestra posterior (a través de una petición POST) del formulario no debería ser
almacenada en caché ya que el formulario puede que contenga entradas del usuario. Para hacerlo, podrías configurar la
opción de [[yii\widgets\FragmentCache::enabled|activado]] (enabled), de la siguiente manera:
```php
if ($this->beginCache($id, ['enabled' => Yii::$app->request->isGet])) {
// ... generar contenido aquí ...
$this->endCache();
}
```
## Almacenamiento en Caché Anidada
El almacenamiento en caché de fragmentos se puede anidar. Es decir, un fragmento de caché puede ser encerrado dentro de
otro fragmento que también se almacena en caché. Por ejemplo, los comentarios se almacenan en una caché de fragmento
interno, y se almacenan conjuntamente con el contenido del artículo en un fragmento de caché exterior. El siguiente
código muestra cómo dos fragmentos de caché pueden ser anidados:
```php
if ($this->beginCache($id1)) {
// ... lógica de generación de contenido externa ...
if ($this->beginCache($id2, $options2)) {
// ... lógica de generación de contenido anidada ...
$this->endCache();
}
// ... lógica de generación de contenido externa ...
$this->endCache();
}
```
Existen diferentes opciones de configuración para las cachés anidadas. Por ejemplo, las cachés internas y las cachés
externas pueden usar diferentes valores de duración. Aún cuando los datos almacenados en la caché externa sean invalidados,
la caché interna puede todavía proporcionar un fragmento válido. Sin embargo, al revés no es cierto. Si la caché externa
es evaluada como válida, seguiría proporcionando la misma copia en caché incluso después de que el contenido en la
caché interna haya sido invalidada. Por lo tanto, hay que tener mucho cuidado al configurar el tiempo de duración o las
dependencias de las cachés anidadas, de lo contrario los fragmentos internos que ya estén obsoletos se pueden seguir
manteniendo en el fragmento externo.
## Contenido Dinámico
Cuando se usa la caché de fragmentos, podrías encontrarte en la situación que un fragmento grande de contenido es
relavitamente estático excepto en uno u otro lugar. Por ejemplo, la cabeza de una página (header) puede que muestre el
menú principal junto al nombre del usuario actual. Otro problema es que el contenido que está siendo almacenado en caché
puede que contenga código PHP que debe ser ejecutado en cada petición (por ejemplo, el código para registrar
un paquete de recursos (asset bundle)). En ambos casos, podríamos resolver el problema con lo que llamamos la
característica de *contenido dinámico*.
Entendemos *contenido dinámico* como un fragmento de salida que no debería ser guardado en caché incluso si está
encerrado dentro de un fragmento de caché. Para hacer el contenido dinámico todo el tiempo, éste ha de ser generado ejecutando
cierto código PHP en cada petición, incluso si el contenido está siendo mostrado desde la caché.
Puedes llamar a [[yii\base\View::renderDynamic()]] dentro de un fragmento almacenado en caché para insertar código
dinámico en el lugar deseado como, por ejemplo, de la siguiente manera,
```php
if ($this->beginCache($id1)) {
// ... lógica de generación de contenido ...
echo $this->renderDynamic('return Yii::$app->user->identity->name;');
// ... lógica de generación de contenido ...
$this->endCache();
}
```
El método [[yii\base\View::renderDynamic()|renderDynamic()]] toma una pieza de código PHP como su parámetro. El valor
devuelto del código PHP se trata como contenido dinámico. El mismo código PHP será ejecutado en cada petición,
sin importar que esté dentro de un fragmento que está siendo servido desde la caché o no.
---
### Guide Es Caching Http (`docs/guide-es/caching-http.md`)
Caché HTTP
==========
Además del almacenamiento de caché en el servidor que hemos descrito en secciones anteriores, las aplicaciones Web
pueden hacer uso de la caché en el lado del cliente para así ahorrar tiempo y recursos para generar y transmitir el
mismo contenido una y otra vez.
Para usar la caché del lado del cliente, puedes configurar [[yii\filters\HttpCache]] como un filtro en el controlador
para aquellas acciones cuyo resultado deba estar almacenado en la caché en el lado del cliente. [[yii\filters\HttpCache|HttpCache]]
solo funciona en peticiones `GET` y `HEAD`. Puede manejar tres tipos de cabeceras (headers) HTTP relacionadas en este tipo de
consultas:
* [[yii\filters\HttpCache::lastModified|Last-Modified]]
* [[yii\filters\HttpCache::etagSeed|Etag]]
* [[yii\filters\HttpCache::cacheControlHeader|Cache-Control]]
## La Cabecera `Last-Modified`
La cabecera `Last-Modified` usa un sello de tiempo para indicar si la página ha sido modificada desde que el cliente la
almacena en la caché.
Puedes configurar la propiedad [[yii\filters\HttpCache::lastModified]] para activar el envío de la cabecera `Last-Modified`.
La propiedad debe ser una llamada de retorno (callable) PHP que devuelva un timestamp UNIX sobre el tiempo de modificación de
la página. El formato de la función de llamada de retorno debe ser el siguiente,
```php
/**
* @param Action $action el objeto acción que se está controlando actualmente
* @param array $params el valor de la propiedad "params"
* @return int un sello de tiempo UNIX que representa el tiempo de modificación de la página
*/
function ($action, $params)
```
El siguiente es un ejemplo haciendo uso de la cabecera `Last-Modified`:
```php
public function behaviors()
{
return [
[
'class' => 'yii\filters\HttpCache',
'only' => ['index'],
'lastModified' => function ($action, $params) {
$q = new \yii\db\Query();
return $q->from('post')->max('updated_at');
},
],
];
}
```
El código anterior establece que la memoria caché HTTP debe ser habilitada únicamente por la acción `index`. Se debe
generar una cabecera HTTP `Last-Modified` basado en el último tiempo de actualización de los artículos. Cuando un
navegador visita la página `index` la primera vez, la página será generada en el servidor y enviada al navegador; Si el
navegador visita la misma página de nuevo y no ningún artículo modificado durante el período, el servidor no volverá a
regenerar la página, y el navegador usará la versión caché del lado del cliente. Como resultado, la representación del
lado del servidor y la transmisión del contenido de la página son ambos omitidos.
## La Cabecera `ETag`
La cabecera "Entity Tag" (o para abreviar `ETag`) usa un hash para representar el contenido de una página. Si la página
ha sido cambiada, el hash también cambiará. Al comparar el hash guardado en el lado del cliente con el hash generado en
el servidor, la caché puede determinar si la página ha cambiado y deber ser retransmitida.
Puedes configurar la propiedad [[yii\filters\HttpCache::etagSeed]] para activar el envío de la cabecera `ETag`.
La propiedad debe ser una función de retorno (callable) PHP que devuelva una semilla para la generación del hash de `ETag`.
El formato de la función de retorno es el siguiente:
```php
/**
* @param Action $action el objeto acción que se está controlando actualmente
* @param array $params el valor de la propiedad "params"
* @return string una cadena usada como semilla para la generación del hash de ETag
*/
function ($action, $params)
```
El siguiente es un ejemplo de cómo usar la cabecera `ETag`:
```php
public function behaviors()
{
return [
[
'class' => 'yii\filters\HttpCache',
'only' => ['view'],
'etagSeed' => function ($action, $params) {
$post = $this->findModel(\Yii::$app->request->get('id'));
return serialize([$post->title, $post->content]);
},
],
];
}
```
El código anterior establece que la caché HTTP debe ser activada únicamente para la acción `view`. Debería generar una
cabecera HTTP `ETag` basándose en el título y contenido del artículo consultado. Cuando un navegador visita la página
`view` por primera vez, la página se generará en el servidor y será enviada al navegador; Si el navegador visita la
misma página de nuevo y no ha ocurrido un cambio en el título o contenido del artículo, el servidor no volverá a generar
la página, y el navegador usará la versión guardada en la caché del lado del cliente. Como resultado, la representación del
lado del servidor y la transmisión del contenido de la página son ambos omitidos.
ETags permiten estrategias de almacenamiento de caché más complejas y/o mucho más precisas que las cabeceras `Last-Modified`.
Por ejemplo, un ETag puede ser invalidado si el sitio Web ha cambiado de tema (theme).
La generación de un ETag que requiera muchos recursos puede echar por tierra el propósito de estar usando `HttpCache` e
introducir una sobrecarga innecesaria, ya que debe ser re-evaluada en cada solicitud (request). Trata de encontrar una
expresión sencilla para invalidar la caché si la página ha sido modificada.
> Note: En cumplimiento con [RFC 7232](https://datatracker.ietf.org/doc/html/rfc7232#section-2.4),
`HttpCache` enviará ambas cabeceras `ETag` y `Last-Modified` si ambas están configuradas. Y si el clientes envía tanto la cabecera `If-None-Match` como la cabecera `If-Modified-Since`, solo la primera será respetada.
## La Cabecera `Cache-Control`
La cabecera `Cache-Control` especifica la directiva general de la caché para páginas. Puedes enviarla configurando la
propiedad [[yii\filters\HttpCache::cacheControlHeader]] con el valor de la cabecera. Por defecto, la siguiente cabecera
será enviada:
```
Cache-Control: public, max-age=3600
```
## Limitador de la Sesión de Caché
Cuando una página utiliza la sesión, PHP enviará automáticamente cabeceras HTTP relacionadas con la caché tal y como se
especifican en `session.cache_limiter` de la configuración INI de PHP. Estas cabeceras pueden interferir o deshabilitar
el almacenamiento de caché que desees de `HttpCache`. Para evitar este problema, por defecto `HttpCache` deshabilitará
automáticamente el envío de estas cabeceras. Si deseas modificar este comportamiento, tienes que configurar la propiedad
[[yii\filters\HttpCache::sessionCacheLimiter]]. La propiedad puede tomar un valor de cadena, incluyendo `public`, `private`,
`private_no_expire`, and `nocache`. Por favor, consulta el manual PHP acerca de [session_cache_limiter()](https://www.php.net/manual/es/function.session-cache-limiter.php)
para una mejor explicación sobre esos valores.
## Implicaciones SEO
Los robots de motores de búsqueda tienden a respetar las cabeceras de caché. Dado que algunos `crawlers` tienen limitado
el número de páginas que pueden rastrear por dominios dentro de un cierto período de tiempo, la introducción de cabeceras
de caché pueden ayudar a la indexación del sitio Web y reducir el número de páginas que deben ser procesadas.
---
### Guide Es Caching Page (`docs/guide-es/caching-page.md`)
Caché de Páginas
================
La caché de páginas se refiere a guardar el contenido de toda una página en el almacenamiento de caché del servidor.
Posteriormente, cuando la misma página sea requerida de nuevo, su contenido será devuelto desde la caché en vez de
volver a generarlo desde cero.
El almacenamiento en caché de páginas está soportado por [[yii\filters\PageCache]], un [filtro de acción](structure-filters.md).
Puede ser utilizado de la siguiente forma en un controlador:
```php
public function behaviors()
{
return [
[
'class' => 'yii\filters\PageCache',
'only' => ['index'],
'duration' => 60,
'variations' => [
\Yii::$app->language,
],
'dependency' => [
'class' => 'yii\caching\DbDependency',
'sql' => 'SELECT COUNT(*) FROM post',
],
],
];
}
```
El código anterior establece que el almacenamiento de páginas en caché debe ser utilizado sólo en la acción `index`; el
contenido de la página debería almacenarse durante un máximo de 60 segundos y ser variado por el idioma actual de la
aplicación; además, el almacenamiento de la página en caché debería ser invalidado si el número total de
artículos ha cambiado.
Como puedes ver, la caché de páginas es muy similar a la [caché de fragmentos](caching-fragment.md). Ambos soportan opciones
tales como `duration`, `dependencies`, `variations`, y `enabled`. Su principal diferencia es que la caché de páginas está
implementado como un [filtro de acción](structure-filters.md) mientras que la caché de fragmentos se hace en un [widget](structure-widgets.md).
Puedes usar la [caché de fragmentos](caching-fragment.md) así como el [contenido dinámico](caching-fragment.md#dynamic-content)
junto con la caché de páginas.
---
### Guide Es Concept Aliases (`docs/guide-es/concept-aliases.md`)
Alias
=====
Loa alias son utilizados para representar rutas o URLs de manera que no tengas que escribir explícitamente rutas absolutas o URLs en tu
proyecto. Un alias debe comenzar con el signo `@` para ser diferenciado de una ruta normal de archivo y de URLs. Los alias definidos
sin el `@` del principio, serán prefijados con el signo `@`.
Yii trae disponibles varios alias predefinidos. Por ejemplo, el alias `@yii` representa la ruta de instalación del
framework Yii; `@web` representa la URL base para la aplicación Web ejecutándose.
Definir Alias
-------------
Para definir un alias puedes llamar a [[Yii::setAlias()]] para una determinada ruta de archivo o URL. Por ejemplo,
```php
// un alias de una ruta de archivos
Yii::setAlias('@foo', '/path/to/foo');
// una alias de un URL
Yii::setAlias('@bar', 'https://www.example.com');
```
> Note: Una ruta de archivo o URL en alias NO debe necesariamente referirse a un archivo o recurso existente.
Dado un alias, puedes derivar un nuevo alias (sin necesidad de llamar [[Yii::setAlias()]]) anexando una barra diagonal `/`
seguida por uno o varios segmentos de la ruta. Llamamos los alias definidos a través de [[Yii::setAlias()]]
*alias de raíz* (root alias), mientras que los alias derivados de ellos *alias derivados* (derived aliases). Por ejemplo,
`@foo` es un alias de raíz, mientras que `@foo/bar/file.php` es un alias derivado.
Puedes definir un alias usando otro alias (ya sea un alias de raíz o derivado):
```php
Yii::setAlias('@foobar', '@foo/bar');
```
Los alias de raíz están usualmente definidos durante la etapa [bootstrapping](runtime-bootstrapping.md) de la aplicación.
Por ejemplo, puedes llamar a [[Yii::setAlias()]] en el [script de entrada](structure-entry-scripts.md).
Por conveniencia, [Application](structure-applications.md) provee una propiedad modificable llamada `aliases` que puedes
configurar en la [configuración](concept-configurations.md) de la aplicación, como por ejemplo,
```php
return [
// ...
'aliases' => [
'@foo' => '/path/to/foo',
'@bar' => 'https://www.example.com',
],
];
```
Resolución de Alias
-------------------
Puedes llamar [[Yii::getAlias()]] para resolver un alias de raíz en la ruta o URL que representa. El mismo método puede
además resolver un alias derivado en su correspondiente ruta de archivo o URL. Por ejemplo,
```php
echo Yii::getAlias('@foo'); // muestra: /path/to/foo
echo Yii::getAlias('@bar'); // muestra: https://www.example.com
echo Yii::getAlias('@foo/bar/file.php'); // muestra: /path/to/foo/bar/file.php
```
La ruta de archivo/URL representado por un alias derivado está determinado por la sustitución de la parte de su alias raíz
con su correspondiente ruta/Url en el alias derivado.
> Note: El método [[Yii::getAlias()]] no comprueba si la ruta/URL resultante hacer referencia a un archivo o recurso existente.
Un alias de raíz puede contener carácteres `/`. El método [[Yii::getAlias()]] es lo suficientemente inteligente para saber
qué parte de un alias es un alias de raíz y por lo tanto determinar correctamente la correspondiente ruta de archivo o URL.
Por ejemplo,
```php
Yii::setAlias('@foo', '/path/to/foo');
Yii::setAlias('@foo/bar', '/path2/bar');
Yii::getAlias('@foo/test/file.php'); // muestra: /path/to/foo/test/file.php
Yii::getAlias('@foo/bar/file.php'); // muestra: /path2/bar/file.php
```
Si `@foo/bar` no está definido como un alias de raíz, la última declaración mostraría `/path/to/foo/bar/file.php`.
Usando Alias
------------
Los alias son utilizados en muchos lugares en Yii sin necesidad de llamar [[Yii::getAlias()]] para convertirlos
en rutas/URLs. Por ejemplo, [[yii\caching\FileCache::cachePath]] puede aceptar tanto una ruta de archivo como un alias
que represente la ruta de archivo, gracias al prefijo `@` el cual permite diferenciar una ruta de archivo
de un alias.
```php
use yii\caching\FileCache;
$cache = new FileCache([
'cachePath' => '@runtime/cache',
]);
```
Por favor, presta atención a la documentación API para ver si una propiedad o el parámetro de un método soporta alias.
Alias Predefinidos
------------------
Yii predefine un conjunto de alias para aliviar la necesidad de hacer referencia a rutas de archivo o URLs que son
utilizadas regularmente. La siguiente es la lista de alias predefinidos por Yii:
- `@yii`: el directorio donde el archivo `BaseYii.php` se encuentra (también llamado el directorio del framework).
- `@app`: la [[yii\base\Application::basePath|ruta base]] de la aplicación que se está ejecutando actualmente.
- `@runtime`: la [[yii\base\Application::runtimePath|ruta de ejecución]] de la aplicación en ejecución. Por defecto `@app/runtime`.
- `@webroot`: el directorio raíz Web de la aplicación Web se está ejecutando actualmente.
- `@web`: la URL base de la aplicación web se ejecuta actualmente. Tiene el mismo valor que [[yii\web\Request::baseUrl]].
- `@vendor`: el [[yii\base\Application::vendorPath|directorio vendor de Composer]]. Por defecto `@app/vendor`.
- `@bower`, el directorio raíz que contiene [paquetes bower](https://bower.io/). Por defecto `@vendor/bower`.
- `@npm`, el directorio raíz que contiene [paquetes npm](https://www.npmjs.com/). Por defecto `@vendor/npm`.
El alias `@yii` se define cuando incluyes el archivo `Yii.php` en tu [script de entrada](structure-entry-scripts.md),
mientras que el resto de los alias están definidos en el constructor de la aplicación cuando se aplica la
[configuración](concept-configurations.md) de la aplicación.
Alias en Extensiones
--------------------
Un alias se define automáticamente por cada [extensión](structure-extensions.md) que ha sido instalada a través de Composer.
El alias es nombrado tras el `namespace` de raíz de la extensión instalada tal y como está declarada en su archivo `composer.json`,
y representa el directorio raíz de la extensión. Por ejemplo, si instalas la extensión `yiisoft/yii2-jui`, tendrás
automáticamente definido el alias `@yii/jui` durante la etapa [bootstrapping](runtime-bootstrapping.md) de la aplicación:
```php
Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');
```
---
### Guide Es Concept Autoloading (`docs/guide-es/concept-autoloading.md`)
Autocarga de clases
===================
Yii depende del [mecanismo de autocarga de clases](https://www.php.net/manual/es/language.oop5.autoload.php) para localizar
e incluir los archivos de las clases requiridas. Proporciona un cargador de clases de alto rendimiento que cumple con el
[estandard PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md).
El cargador se instala cuando incluyes el archivo `Yii.php`.
> Note: Para simplificar la descripción, en esta sección sólo hablaremos de la carga automática de clases. Sin embargo,
ten en cuenta que el contenido que describimos aquí también se aplica a la autocarga de interfaces y rasgos (Traits).
Usando el Autocargador de Yii
-----------------------------
Para utilizar el cargador automático de clases de Yii, deberías seguir dos reglas básicas cuando desarrolles y nombres tus
clases:
* Cada clase debe estar bajo un espacio de nombre (namespace). Por ejemplo `foo\bar\MyClass`.
* Cada clase debe estar guardada en un archivo individual cuya ruta está determinada por el siguiente algoritmo:
```php
// $className es un nombre completo de clase con las iniciales barras invertidas.
$classFile = Yii::getAlias('@' . str_replace('\\', '/', $className) . '.php');
```
Por ejemplo, si el nombre de una clase es `foo\bar\MyClass`, el [alias](concept-aliases.md) la correspondiente ruta de
archivo de la clase sería `@foo/bar/MyClass.php`. Para que este sea capaz de ser resuelto como una ruta de archivo, ya sea
`@foo` o `@foo/bar` debe ser un [alias de raíz](concept-aliases.md#defining-aliases) (root alias).
Cuando utilizas la [Plantilla de Aplicación Básica](start-installation.md), puede que pongas tus clases bajo el nivel superior
de espacio de nombres `app` para que de esta manera pueda ser automáticamente cargado por Yii sin tener la necesidad de
definir un nuevo alias. Esto es porque `@app` es un [alias predefinido](concept-aliases.md#predefined-aliases), y el
nombre de una clase tal como `app\components\MyClass` puede ser resuelto en el archivo de la clase `AppBasePath/components/MyClass.php`,
de acuerdo con el algoritmo previamente descrito.
En la [Plantilla de Aplicación Avanzada](tutorial-advanced-app.md), cada nivel tiene su propio alias. Por ejemplo, el nivel
`front-end` tiene un alias de raíz `@frontend` mientras que el nivel `back-end` tiene `@backend`. Como resultado, es posible
poner las clases `front-end` bajo el espacio de nombres `frontend` mientras que las clases `back-end` pueden hacerlo bajo
`backend`. Esto permitirá que estas clases sean automaticamente cargadas por el autocargador de Yii.
Mapa de Clases
--------------
El autocargador de clases de Yii soporta el *mapa de clases*, que mapea nombres de clases to sus correpondientes rutas de
archvios. Cuando el autocargador esta cargando una clase, primero chequeará si la clase se encuentra en el mapa. Si es así,
el correspondiente archivo será incluido directamente sin más comprobación. Esto hace que la clase se cargue muy rápidamente.
De hecho, todas las clases de Yii son autocargadas de esta manera.
Puedes añadir una clase al mapa de clases `Yii::$classMap` de la siguiente forma,
```php
Yii::$classMap['foo\bar\MyClass'] = 'path/to/MyClass.php';
```
[Alias](concept-aliases.md) puede ser usado para especificar la ruta de archivos de clases. Deberías iniciar el mapeo de
clases en el proceso [bootstrapping](runtime-bootstrapping.md) de la aplicación para que de esta manera el mapa esté listo
antes de que tus clases sean usadas.
Usando otros Autocargadores
---------------------------
Debido a que Yii incluye Composer como un gestor de dependencias y extensions, es recomendado que también instales el
autocargador de Composer. Si estás usando alguna librería externa que requiere sus autocargadores, también deberías
instalarlos.
Cuando se utiliza el cargador de clases automático de Yii conjuntamente con otros autocargadores, deberías incluir el
archivo `Yii.php` *después* de que todos los demás autocargadores se hayan instalado. Esto hará que el autocargador de
Yii sea el primero en responder a cualquier petición de carga automática de clases. Por ejemplo, el siguiente código ha
sido extraido del [script de entrada](structure-entry-scripts.md) de la [Plantilla de Aplicación Básica](start-installation.md).
La primera línea instala el autocargador de Composer, mientras que la segunda línea instala el autocargador de Yii.
```php
require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';
```
Puedes usar el autocargador de Composer sin el autocargador de Yii. Sin embargo, al hacerlo, la eficacia de la carga de
tus clases puede que se degrade, y además deberías seguir las reglas establecidas por Composer para que tus clases pudieran
ser autocargables.
> Note: Si no deseas utilizar el autocargador de Yii, tendrás que crear tu propia versión del archivo `Yii.php` e
incluirlo en tu [script de entrada](structure-entry-scripts.md).
Carga Automática de Clases de Extensiones
-----------------------------------------
El autocargador de Yii es capaz de autocargar clases de [extensiones](structure-extensions.md). El único requirimiento es
que la extensión especifique correctamente la sección de `autoload` (autocarga) en su archivo `composer.json`. Por favor,
consulta la [documentación de Composer](https://getcomposer.org/doc/04-schema.md#autoload) para más detalles acerca de la
especificación `autoload`.
En el caso de que no quieras usar el autocargador de Yii, el autocargador de Composer podría cargar las clases de extensiones
por tí.
---
### Guide Es Concept Behaviors (`docs/guide-es/concept-behaviors.md`)
Comportamientos
===============
Comportamientos son instancias de [[yii\base\Behavior]] o sus clases "hija". Comportamientos, también conocido como
[mixins](https://es.wikipedia.org/wiki/Mixin), te permiten mejorar la funcionalidad de un [[yii\base\Component|componente]]
existente sin necesidad de modificar su herencia de clases.
Cuando un comportamiento se une a un componente, "inyectará" sus métodos y propiedades dentro del componente, y podrás
acceder a esos métodos y propiedades como si hubieran estado definidos por la clase de componente. Además, un
comportamiento puede responder a [eventos](concept-events.md) disparados por el componente de modo que se pueda personalizar
o adaptar a la ejecución normal del código del componente.
Definiendo comportamientos
--------------------------
Para definir un comportamiento, se debe crear una clase que exiende [[yii\base\Behavior]], o se extiende una clase hija. Por ejemplo:
```php
namespace app\components;
use yii\base\Behavior;
class MyBehavior extends Behavior
{
public $prop1;
private $_prop2;
public function getProp2()
{
return $this->_prop2;
}
public function setProp2($value)
{
$this->_prop2 = $value;
}
public function foo()
{
// ...
}
}
```
El código anterior define la clase de comportamiento (behavior) app\components\MyBehavior`, con dos propiedades --
`prop1` y `prop2`--y un método `foo()`. Tenga en cuenta que la propiedad `prop2`
se define a través de la getter `getProp2()` y el setter `setProp2()`. Este caso es porque [[yii\base\Behavior]] extiende [[yii\base\BaseObject]] y por lo tanto se apoya en la definición de [propiedades](concept-properties.md) via getters y setters.
Debido a que esta clase es un comportamiento, cuando está unido a un componente, el componente también tienen la propiedad `prop1` y `prop2` y el método `foo()`.
> Tip: Dentro de un comportamiento, puede acceder al componente que el comportamiento está unido a través de la propiedad [[yii\base\Behavior::owner]].
Gestión de eventos de componentes
---------------------------------
Si un comportamiento necesita responder a los acontecimientos desencadenados por el componente al que está unido, se debe reemplazar el método [[yii\base\Behavior::events()]]. Por ejemplo:
```php
namespace app\components;
use yii\db\ActiveRecord;
use yii\base\Behavior;
class MyBehavior extends Behavior
{
// ...
public function events()
{
return [
ActiveRecord::EVENT_BEFORE_VALIDATE => 'beforeValidate',
];
}
public function beforeValidate($event)
{
// ...
}
}
```
El método [[yii\base\Behavior::events()|events()]] debe devolver una lista de eventos y sus correspondientes controladores.
El ejemplo anterior declara que el evento [[yii\db\ActiveRecord::EVENT_BEFORE_VALIDATE|EVENT_BEFORE_VALIDATE]] existe y esta exists y define su controlador, `beforeValidate()`. Al especificar un controlador de eventos, puede utilizar uno de los siguientes formatos:
* una cadena que se refiere al nombre de un método de la clase del comportamiento, como el ejemplo anterior
* un arreglo de objeto o nombre de clase, y un nombre de método como una cadena (sin paréntesis), ej., `[$object, 'methodName']`;
* una función anónima
La firma de un controlador de eventos debe ser la siguiente, donde `$ event` refiere al parámetro de evento. Por favor, consulte la sección [Eventos](concept-events.md) para más detalles sobre los eventos.
```php
function ($event) {
}
```
Vinculando Comportamientos
--------------------------
Puedes vincular un comportamiento a un [[yii\base\Component|componente]] ya sea estática o dinámicamente. La primera forma
es la más comúnmente utilizada en la práctica.
Para unir un comportamiento estáticamente, reemplaza el método [[yii\base\Component::behaviors()|behaviors()]] dde la clase de componente a la que se une el comportamiento. El método [[yii\base\Component::behaviors()|behaviors()]] debe devolver una lista de comportamiento [configuraciones](concept-configurations.md).
Cada configuración de comportamiento puede ser un nombre de clase de comportamiento o un arreglo de configuración:
```php
namespace app\models;
use yii\db\ActiveRecord;
use app\components\MyBehavior;
class User extends ActiveRecord
{
public function behaviors()
{
return [
// anonymous behavior, behavior class name only
MyBehavior::class,
// named behavior, behavior class name only
'myBehavior2' => MyBehavior::class,
// anonymous behavior, configuration array
[
'class' => MyBehavior::class,
'prop1' => 'value1',
'prop2' => 'value2',
],
// named behavior, configuration array
'myBehavior4' => [
'class' => MyBehavior::class,
'prop1' => 'value1',
'prop2' => 'value2',
]
];
}
}
```
Puedes asociciar un nombre a un comportamiento especificándolo en la clave de la matriz correspondiente a la configuración
del comportamiento. En este caso, el comportamiento puede ser llamado un *comportamiento nombrado* (named behavior). En
el ejemplo anterior, hay dos tipos de comportamientos nombrados: `myBehavior2` y `myBehavior4`. Si un comportamiento
no está asociado con un nombre, se le llama *comportamiento anónimo* (anonymous behavior).
Para vincular un comportamiento dinámicamente, llama al método [[yii\base\Component::attachBehavior()]] desde el componente al
que se le va a unir el comportamiento:
```php
use app\components\MyBehavior;
// vincular un objeto comportamiento "behavior"
$component->attachBehavior('myBehavior1', new MyBehavior());
// vincular una clase comportamiento
$component->attachBehavior('myBehavior2', MyBehavior::class);
// asociar una matriz de configuración
$component->attachBehavior('myBehavior3', [
'class' => MyBehavior::class,
'prop1' => 'value1',
'prop2' => 'value2',
]);
```
Puede vincular múltiples comportamientos a la vez mediante el uso del método [[yii\base\Component::attachBehaviors()]]. Por ejemplo,
```php
$component->attachBehaviors([
'myBehavior1' => new MyBehavior(), // un comportamiento nombrado
MyBehavior::class, // un comportamiento anónimo
]);
```
También puedes asociar comportamientos a traves de [configuraciones](concept-configurations.md) como el siguiente:
```php
[
'as myBehavior2' => MyBehavior::class,
'as myBehavior3' => [
'class' => MyBehavior::class,
'prop1' => 'value1',
'prop2' => 'value2',
],
]
```
Para más detalles, por favor visita la sección [Configuraciones](concept-configurations.md#configuration-format).
Usando comportamientos
----------------------
Para poder utilizar un comportamiento, primero tienes que unirlo a un [[yii\base\Component|componente]] según las instrucciones anteriores. Una vez que un comportamiento ha sido vinculado a un componente, su uso es sencillo.
Puedes usar a una variable *pública* o a una [propiedad](concept-properties.md) definida por un `getter` y/o un `setter`
del comportamiento a través del componente con el que se ha vinculado:
```php
// "prop1" es una propiedad definida en la clase comportamiento
echo $component->prop1;
$component->prop1 = $value;
```
También puedes llamar métodos *públicos* del comportamiento de una forma similar:
```php
// foo() es un método público definido dentro de la clase comportamiento
$component->foo();
```
Como puedes ver, aunque `$component` no tiene definida `prop1` y `bar()`, que se pueden utilizar como si son parte
de la definición de componentes debido al comportamiento vinculado.
Si dos comportamientos definen la misma propiedad o método y ambos están vinculados con el mismo componente, el
comportamiento que ha sido vinculado *primero* tendrá preferencia cuando se esté accediendo a la propiedad o método.
Un comportamiento puede estar asociado con un nombre cuando se une a un componente. Si este es el caso, es posible
acceder al objeto de comportamiento mediante el nombre, como se muestra a continuación,
```php
$behavior = $component->getBehavior('myBehavior');
```
También puedes acceder a todos los comportamientos vinculados al componente:
```php
$behaviors = $component->getBehaviors();
```
Desasociar Comportamientos
--------------------------
Para desasociar un comportamiento, puedes llamar el método [[yii\base\Component::detachBehavior()]] con el nombre con el
que se le asoció:
```php
$component->detachBehavior('myBehavior1');
```
También puedes desvincular *todos* los comportamientos:
```php
$component->detachBehaviors();
```
Utilizando `TimestampBehavior`
-----------------------------
Para terminar, vamos a echar un vistazo a [[yii\behaviors\TimestampBehavior]]. Este comportamiento soporta de forma
automática la actualización de atributos timestamp de un modelo [[yii\db\ActiveRecord|Registro Activo]]
(Active Record) en cualquier momento donde se guarda el modelo (ej., en la inserción o actualización).
Primero, vincula este comportamiento a la clase [[yii\db\ActiveRecord|Active Record]] que desees utilizar.
```php
namespace app\models\User;
use yii\db\ActiveRecord;
use yii\behaviors\TimestampBehavior;
class User extends ActiveRecord
{
// ...
public function behaviors()
{
return [
[
'class' => TimestampBehavior::class,
'attributes' => [
ActiveRecord::EVENT_BEFORE_INSERT => ['created_at', 'updated_at'],
ActiveRecord::EVENT_BEFORE_UPDATE => ['updated_at'],
],
],
];
}
}
```
La configuración del comportamiento anterior especifica que
* cuando el registro está siendo insertado, el comportamiento debe asignar el sello de tiempo actual a los atributos
`created_at` y `updated_at`;
* cuando el registro está siendo actualizado, el comportamiento debe asignar el sello de tiempo actual al atributo
`updated_at`.
Ahora si tienes un objeto `User` e intentas guardarlo, descubrirás que sus campos `created_at` y `updated_at` están
automáticamente actualizados con el sello de tiempo actual:
```php
$user = new User;
$user->email = 'test@example.com';
$user->save();
echo $user->created_at; // muestra el sello tiempo actual (timestamp)
```
El comportamiento [[yii\behaviors\TimestampBehavior|TimestampBehavior]] también ofrece un método muy útil llamado
[[yii\behaviors\TimestampBehavior::touch()|touch()]], que asigna el sello de tiempo actual a un atributo especificado y lo guarda automáticamente en la base de datos:
```php
$user->touch('login_time');
```
Comparación con Traits
----------------------
Mientras que los comportamientos son similares a [traits](https://www.php.net/manual/es/language.oop5.traits.php) en cuanto que ambos "inyectan" sus
métodos y propiedades a la clase primaria, son diferentes en muchos aspectos. Tal y como se describe abajo, los dos
tienen sus ventajas y desventajas. Son más como complementos el uno al otro en lugar de alternativas.
### Razones para utilizar comportamientos
Las clases de comportamientos, como todas las clases, soportan herencias. Traits, por otro lado, pueden ser
considerados como un copia-y-pega de PHP. Ellos no soportan la herencia de clases.
Los comportamientos pueden ser asociados y desasociados a un componente dinámicamente sin necesidad de que la clase del
componente sea modificada. Para usar un trait, debes modificar la clase que la usa.
Los comportamientos son configurables mientras que los traits no.
Los comportamientos pueden personalizar la ejecución de un componente al responder a sus eventos.
Cuando hay un conflicto de nombre entre los diferentes comportamientos vinculados a un mismo componente, el conflicto es
automáticamente resuelto respetando al que ha sido asociado primero.
El conflicto de nombres en traits requiere que manualmente sean resueltos cambiando el nombre de las propiedades o métodos afectados.
### Razones para utilizar los Traits
Los Traits son mucho más eficientes que los comportamientos debido a que los últimos son objetos que consumen tiempo y
memoria.
Los IDEs (Programas de desarrollo) son más amigables con traits ya que son una construcción del lenguaje nativo.
---
### Guide Es Concept Components (`docs/guide-es/concept-components.md`)
Componentes
===========
Los componentes son los principales bloques de construcción de las aplicaciones Yii. Los componentes son instancias de [[yii\base\Component]] o de una clase extendida. Las tres características principales que los componentes proporcionan
a las otras clases son:
* [Propiedades](concept-properties.md)
* [Eventos](concept-events.md)
* [Comportamientos](concept-behaviors.md)
Por separado y combinadas, estas características hacen que las clases Yii sean mucho mas personalizables y sean mucho más fáciles de usar. Por ejemplo, el incluido [[yii\jui\DatePicker|widget de selección de fecha]], un componente de la interfaz de usuario, puede ser utilizado en una [vista](structure-view.md) para generar un DatePicker interactivo:
```php
use yii\jui\DatePicker;
echo DatePicker::widget([
'language' => 'ru',
'name' => 'country',
'clientOptions' => [
'dateFormat' => 'yy-mm-dd',
],
]);
```
Las propiedades del widget son fácilmente modificables porque la clase se extiende de [[yii\base\Component]].
Mientras que los componentes son muy potentes, son un poco más pesados que los objetos normales, debido al hecho de que necesitan más memoria y tiempo de CPU para poder soportar [eventos](concept-events.md) y [comportamientos](concept-behaviors.md) en particular.
Si tus componentes no necesitan estas dos características, deberías considerar extender tu componente directamente de [[yii\base\BaseObject]] en vez de [[yii\base\Component]]. De esta manera harás que tus componentes sean mucho más eficientes que objetos PHP normales, pero con el añadido soporte para [propiedades](concept-properties.md).
Cuando extiendes tu clase de [[yii\base\Component]] o [[yii\base\BaseObject]], se recomienda que sigas las siguientes convenciones:
- Si sobrescribes el constructor, especifica un parámetro `$config` como el *último* parámetro del constructor, y después pasa este parámetro al constructor padre.
- Siempre llama al constructor padre al *final* de su propio constructor.
- Si sobrescribes el método [[yii\base\BaseObject::init()]], asegúrese de llamar la implementación padre de `init` * al principio * de su método` init`.
Por ejemplo:
```php
namespace yii\components\MyClass;
use yii\base\BaseObject;
class MyClass extends BaseObject
{
public $prop1;
public $prop2;
public function __construct($param1, $param2, $config = [])
{
// ... inicialización antes de la configuración está siendo aplicada
parent::__construct($config);
}
public function init()
{
parent::init();
// ... inicialización después de la configuración esta siendo aplicada
}
}
```
Siguiendo esas directrices hará que tus componentes sean [configurables](concept-configurations.md) cuando son creados. Por ejemplo:
```php
$component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]);
// alternativamente
$component = \Yii::createObject([
'class' => MyClass::class,
'prop1' => 3,
'prop2' => 4,
], [1, 2]);
```
> Info: Mientras que el enfoque de llamar [[Yii::createObject()]] parece mucho más complicado, es mucho más potente debido al hecho de que se implementa en la parte superior de un [contenedor de inyección de dependencia](concept-di-container.md).
La clase [[yii\base\BaseObject]] hace cumplir el siguiente ciclo de vida del objeto:
1. Pre-inicialización en el constructor. Puedes establecer los valores predeterminados de propiedades aquí.
2. Configuración del objeto a través de `$config`. La configuración puede sobrescribir los valores prdeterminados dentro del constructor.
3. Post-inicialización dentro de [[yii\base\BaseObject::init()|init()]]. Puedes sobrescribir este método para realizar comprobaciones de validez y normalización de las propiedades.
4. Llamadas a métodos del objeto.
Los tres primeros pasos ocurren dentro del constructor del objeto. Esto significa que una vez obtengas la instancia de un objeto, ésta ha sido inicializada para que puedas utilizarla adecuadamente.
---
### Guide Es Concept Configurations (`docs/guide-es/concept-configurations.md`)
Configuración
==============
Las configuraciones se utilizan ampliamente en Yii al crear nuevos objetos o inicializar los objetos existentes. Las configuraciones por lo general incluyen el nombre de la clase del objeto que se está creando, y una lista de los valores iniciales que deberían ser asignadas a las del [propiedades](concept-properties.md) objeto. Las configuraciones también pueden incluir una lista de manipuladores que deban imponerse a del objeto [eventos](concept-events.md) y/o una lista de [comportamientos](concept-behaviors.md) que también ha de atribuirse al objeto.
A continuación, una configuración que se utiliza para crear e inicializar una conexión a base de datos:
```php
$config = [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
];
$db = Yii::createObject($config);
```
El método [[Yii::createObject()]] toma una matriz de configuración como su argumento, y crea un objeto intanciando la clase llamada en la configuración. Cuando se crea una instancia del objeto, el resto de la configuración se utilizará para inicializar las propiedades del objeto, controladores de eventos y comportamientos.
Si usted ya tiene un objeto, puede usar [[Yii::configure()]] para inicializar las propiedades del objeto con una matriz de configuración:
```php
Yii::configure($object, $config);
```
Tenga en cuenta que en este caso, la matriz de configuración no debe contener un elemento `class`.
## Formato de Configuración
El formato de una configuración se puede describir formalmente como:
```php
[
'class' => 'ClassName',
'propertyName' => 'propertyValue',
'on eventName' => $eventHandler,
'as behaviorName' => $behaviorConfig,
]
```
donde
* El elemento `class` especifica un nombre de clase completo para el objeto que se está creando.
* Los elementos `propertyName` especifica los valores iniciales de la propiedad con nombre. Las claves son los nombres de las propiedades y los valores son los valores iniciales correspondientes. Sólo los miembros de variables públicas y [propiedades](concept-properties.md) definidas por getters/setters se pueden configurar.
* Los elementos `on eventName` especifican qué manipuladores deberán adjuntarse al del objeto [eventos](concept-events.md). Observe que las claves de matriz se forman prefijando nombres de eventos con `on`. Por favor, consulte la sección [Eventos](concept-events.md) para los formatos de controlador de eventos compatibles.
* Los elementos `as behaviorName` especifican qué [comportamientos](concept-behaviors.md) deben adjuntarse al objeto. Observe que las claves de matriz se forman prefijando nombres de comportamiento con `as`; el valor, `$behaviorConfig`, representa la configuración para la creación de un comportamiento, como una configuración normal descrita aquí.
A continuación se muestra un ejemplo de una configuración con los valores de propiedad iniciales, controladores de eventos y comportamientos:
```php
[
'class' => 'app\components\SearchEngine',
'apiKey' => 'xxxxxxxx',
'on search' => function ($event) {
Yii::info("Keyword searched: " . $event->keyword);
},
'as indexer' => [
'class' => 'app\components\IndexerBehavior',
// ... property init values ...
],
]
```
## Usando Configuraciones
Las configuraciones se utilizan en muchos lugares en Yii. Al comienzo de esta sección, hemos demostrado cómo crear un objeto según una configuración mediante el uso de [[Yii::createObject()]]. En este apartado, vamos a describir configuraciones de aplicaciones y configuraciones widget - dos principales usos de configuraciones.
### Configuraciones de aplicación
Configuración para una [aplicación](structure-applications.md) es probablemente una de las configuraciones más complejas. Esto se debe a que la clase [[yii\web\Application|aplicación]] tiene un montón de propiedades y eventos configurables. Más importante aún, su propiedad [[yii\web\Application::components|componentes]] que puede recibir una gran variedad de configuraciones para crear componentes que se registran a través de la aplicación. Lo siguiente es un resumen del archivo de configuración de la aplicación para la [plantilla básica de la aplicación](start-installation.md).
```php
$config = [
'id' => 'basic',
'basePath' => dirname(__DIR__),
'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'mailer' => [
'class' => 'yii\swiftmailer\Mailer',
],
'log' => [
'class' => 'yii\log\Dispatcher',
'traceLevel' => YII_DEBUG ? 3 : 0,
'targets' => [
[
'class' => 'yii\log\FileTarget',
],
],
],
'db' => [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=stay2',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
],
],
];
```
La configuración no tiene una clave `class`. Esto es porque se utiliza como sigue en un [script de entrada](structure-entry-scripts.md), donde ya se le da el nombre de la clase,
```php
(new yii\web\Application($config))->run();
```
Para más detalles sobre la configuración de la propiedad `components` de una aplicación se puede encontrar en la sección [Aplicación](structure-applications.md) y la sección [Localizador de Servicio](concept-service-locator.md).
### Configuración Widget
Cuando se utiliza [widgets](structure-widgets.md), a menudo es necesario utilizar las configuraciones para personalizar las propiedades de widgets. Tanto los metodos [[yii\base\Widget::widget()]] y [[yii\base\Widget::begin()]] pueden usarse para crear un widget. Toman un arreglo de configuración, como el siguiente,
```php
use yii\widgets\Menu;
echo Menu::widget([
'activateItems' => false,
'items' => [
['label' => 'Home', 'url' => ['site/index']],
['label' => 'Products', 'url' => ['product/index']],
['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
],
]);
```
El código anterior crea un widget `Menu` e inicializa su propiedad `activeItems` en falsa. La propiedad `items` también se configura con elementos de menú que se muestran.
Tenga en cuenta que debido a que el nombre de la clase ya está dado, la matriz de configuración no deben tener la clave `class`.
## Archivos de Configuración
Cuando una configuración es muy compleja, una práctica común es almacenarla en uno o múltiples archivos PHP, conocidos como *archivos de configuración*. Un archivo de configuración devuelve un array de PHP que representa la configuración. Por ejemplo, es posible mantener una configuración de la aplicación en un archivo llamado `web.php`, como el siguiente,
```php
return [
'id' => 'basic',
'basePath' => dirname(__DIR__),
'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
'components' => require __DIR__ . '/components.php',
];
```
Debido a que la configuración `componentes` es compleja también, se guarda en un archivo separado llamado `components.php` y "requerir" este archivo en `web.php` como se muestra arriba. El contenido de `components.php` es el siguiente,
```php
return [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'mailer' => [
'class' => 'yii\swiftmailer\Mailer',
],
'log' => [
'class' => 'yii\log\Dispatcher',
'traceLevel' => YII_DEBUG ? 3 : 0,
'targets' => [
[
'class' => 'yii\log\FileTarget',
],
],
],
'db' => [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=stay2',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
],
];
```
Para obtener una configuración almacenada en un archivo de configuración, simplemente "requerir" este, como el siguiente:
```php
$config = require 'path/to/web.php';
(new yii\web\Application($config))->run();
```
## Configuraciones por Defecto
El método [[Yii::createObject()]] es implementado en base a [contenedor de inyección de dependencia](concept-di-container.md). Le permite especificar un conjunto de los llamados *configuraciones predeterminadas* que se aplicarán a todos los casos de las clases especificadas cuando se crean utilizando [[Yii::createObject()]]. Las configuraciones por defecto se puede especificar llamando `Yii::$container->set()` en el código [bootstrapping](runtime-bootstrapping.md).
Por ejemplo, si desea personalizar [[yii\widgets\LinkPager]] para que TODO enlace de búsqueda muestre como máximo 5 botones de página (el valor por defecto es 10), puede utilizar el siguiente código para lograr este objetivo,
```php
\Yii::$container->set('yii\widgets\LinkPager', [
'maxButtonCount' => 5,
]);
```
Sin utilizar las configuraciones predeterminadas, usted tendría que configurar `maxButtonCount` en cada lugar en el que utiliza enlace paginador.
## Constantes de Entorno
Las configuraciones a menudo varían de acuerdo al entorno en que se ejecuta una aplicación. Por ejemplo, en el entorno de desarrollo, es posible que desee utilizar una base de datos llamada `mydb_dev`, mientras que en servidor de producción es posible que desee utilizar la base de datos `mydb_prod`. Para facilitar la conmutación de entornos, Yii proporciona una constante llamado `YII_ENV` que se puede definir en el [script de entrada](structure-entry-scripts.md) de su aplicación. Por ejemplo,
```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```
Usted puede definir `YII_ENV` como uno de los valores siguientes:
- `prod`: entorno de producción. La constante `YII_ENV_PROD` evaluará como verdadero.
Este es el valor por defecto de `YII_ENV` si no esta definida.
- `dev`: entorno de desarrollo. La constante `YII_ENV_DEV` evaluará como verdadero.
- `test`: entorno de pruebas. La constante `YII_ENV_TEST` evaluará como verdadero.
Con estas constantes de entorno, puede especificar sus configuraciones condicionales basado en el entorno actual. Por ejemplo, la configuración de la aplicación puede contener el siguiente código para permitir que el [depurador y barra de herramientas de depuración](tool-debugger.md) en el entorno de desarrollo.
```php
$config = [...];
if (YII_ENV_DEV) {
// configuration adjustments for 'dev' environment
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
}
return $config;
```
---
### Guide Es Concept Di Container (`docs/guide-es/concept-di-container.md`)
Contenedor de Inyección de Dependencias
=======================================
Un contenedor de Inyección de Dependencias (ID), es un objeto que sabe como instancias y configurar objetos y sus
objetos dependientes. El [articulo de Martin](https://martinfowler.com/articles/injection.html) contiene una buena
explicación de porque son útiles los contenedores de ID. A continuación explicaremos como usar el contenedor de ID que
proporciona Yii.
Inyección de Dependencias
-------------------------
Yii proporciona la función de contenedor de ID mediante la clase [[yii\di\Container]]. Soporta los siguientes tipos
de ID:
* Inyección de constructores;
* Inyección de setters y propiedades;
* Inyección de [llamadas de retorno PHP](https://www.php.net/manual/es/language.types.callable.php);
### Inyección de Constructores
El contenedor de ID soporta inyección de constructores con la ayuda de los indicios (hint) de tipo para los parámetros del
constructor. Los indicios de tipo le proporcionan información al contenedor para saber cuáles son las clases o
interfaces dependientes al usarse para crear un nuevo objeto. El contenedor intentara obtener las instancias de las
clases o interfaces dependientes y las inyectará dentro del nuevo objeto mediante el constructor. Por ejemplo,
```php
class Foo
{
public function __construct(Bar $bar)
{
}
}
$foo = $container->get('Foo');
// que es equivalente a:
$bar = new Bar;
$foo = new Foo($bar);
```
### Inyección de Setters y Propiedades
La inyección de setters y propiedades se admite a través de [configuraciones](concept-configurations.md). Cuando se
registra una dependencia o se crea un nuevo objeto, se puede proporcionar una configuración que usará el contenedor
para inyectar las dependencias a través de sus correspondientes setters y propiedades. Por ejemplo,
```php
use yii\base\BaseObject;
class Foo extends BaseObject
{
public $bar;
private $_qux;
public function getQux()
{
return $this->_qux;
}
public function setQux(Qux $qux)
{
$this->_qux = $qux;
}
}
$container->get('Foo', [], [
'bar' => $container->get('Bar'),
'qux' => $container->get('Qux'),
]);
```
### Inyección de Llamadas de retorno PHP
En este caso, el contenedor usará una llamada de retorno PHP registrada para construir una nueva instancia de una
clase. La llamada de retorno se responsabiliza de que dependencias debe inyectar al nuevo objeto creado. Por ejemplo,
```php
$container->set('Foo', function ($container, $params, $config) {
return new Foo(new Bar);
});
$foo = $container->get('Foo');
```
Registro de dependencias
------------------------
Se puede usar [[yii\di\Container::set()]] para registrar dependencias. El registro requiere un nombre de dependencia
así como una definición de dependencia. Un nombre de dependencia puede ser un nombre de clase, un nombre de interfaz,
o un nombre de alias; y una definición de dependencia puede ser un nombre de clase, un array de configuración, o una
llamada de retorno PHP.
```
/* Detailed source-code truncated for AI context efficiency. */
```
> Tip: Si un nombre de dependencia es el mismo que la definición de dependencia, no es necesario registrarlo con
el contenedor de ID.
Una dependencia registrada mediante `set()` generará una instancia cada vez que se necesite la dependencia. Se puede
usar [[yii\di\Container::setSingleton()]] para registrar una dependencia que genere una única instancia:
```php
$container->setSingleton('yii\db\Connection', [
'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
]);
```
Resolución de Dependencias
--------------------------
Una ves se hayan registrado las dependencias, se puede usar el contenedor de ID para crear nuevos objetos, y el
contenedor resolverá automáticamente las dependencias instanciándolas e inyectándolas dentro de los nuevos objetos
creados. La resolución de dependencias es recursiva, esto significa que si una dependencia tiene otras dependencias,
estas dependencias también se resolverán automáticamente.
Se puede usar [[yii\di\Container::get()]] para crear nuevos objetos. El método obtiene el nombre de dependencia, que
puede ser un nombre de clase, un nombre de interfaz o un nombre de alias. El nombre de dependencia puede estar
registrado o no mediante `set()` o `setSingleton()`. Se puede proporcionar opcionalmente un listado de los parámetros
del constructor de clase y una [configuración](concept-configurations.md) para configurar los nuevos objetos creados.
Por ejemplo,
```php
// "db" ha sido registrado anteriormente como nombre de alias
$db = $container->get('db');
// equivalente a: $engine = new \app\components\SearchEngine($apiKey, ['type' => 1]);
$engine = $container->get('app\components\SearchEngine', [$apiKey], ['type' => 1]);
```
Por detrás, el contenedor de ID efectúa mucho más trabajo la creación de un nuevo objeto. El contenedor primero
inspeccionará la clase constructora para encontrar los nombres de clase o interfaces dependientes y después
automáticamente resolverá estas dependencias recursivamente.
El siguiente código muestra un ejemplo más sofisticado. La clase `UserLister` depende del un objeto que implementa la
interfaz `UserFinderInterface`; la clase `UserFinder` implementa la interfaz y depende del objeto `Connection`. Todas
estas dependencias se declaran a través de insinuaciones (hinting) de los parámetros del constructor de clase. Con el
registro de dependencia de propiedades, el contenedor de ID puede resolver las dependencias automáticamente y crear
una nueva instancia de `UserLister` con una simple llamada a `get('userLister')`.
```php
namespace app\models;
use yii\base\BaseObject;
use yii\db\Connection;
use yii\di\Container;
interface UserFinderInterface
{
function findUser();
}
class UserFinder extends BaseObject implements UserFinderInterface
{
public $db;
public function __construct(Connection $db, $config = [])
{
$this->db = $db;
parent::__construct($config);
}
public function findUser()
{
}
}
class UserLister extends BaseObject
{
public $finder;
public function __construct(UserFinderInterface $finder, $config = [])
{
$this->finder = $finder;
parent::__construct($config);
}
}
$container = new Container;
$container->set('yii\db\Connection', [
'dsn' => '...',
]);
$container->set('app\models\UserFinderInterface', [
'class' => 'app\models\UserFinder',
]);
$container->set('userLister', 'app\models\UserLister');
$lister = $container->get('userLister');
// que es equivalente a:
$db = new \yii\db\Connection(['dsn' => '...']);
$finder = new UserFinder($db);
$lister = new UserLister($finder);
```
Uso Practico
------------
Yii crea un contenedor de ID cuando se incluye el archivo `Yii.php` en el
[script de entrada](structure-entry-scripts.md) de la aplicación. Cuando se llama a [[Yii::createObject()]] el método
realmente llama al contenedor del método [[yii\di\Container::get()|get()]] para crear un nuevo objeto. Como se ha
comentado anteriormente, el contenedor de ID resolverá automáticamente las dependencias (si las hay) y las inyectará
dentro del nuevo objeto creado. Debido a que Yii utiliza [[Yii::createObject()]] en la mayor parte del núcleo (core)
para crear nuevo objetos, podemos personalizar los objetos globalmente para que puedan tratar con [[Yii::$container]].
Por ejemplo, se puede personalizar globalmenete el numero predeterminado de números de botones de paginación de
[[yii\widgets\LinkPager]]:
```php
\Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
```
Ahora si se usa el widget en una vista con el siguiente código, la propiedad `maxButtonCount` será inicializada con
valor 5 en lugar de 10 que es el valor predeterminado definido en la clase.
```php
echo \yii\widgets\LinkPager::widget();
```
Se puede sobrescribir el valor establecido mediante el contenedor de ID, como a continuación:
```php
echo \yii\widgets\LinkPager::widget(['maxButtonCount' => 20]);
```
Otro ejemplo es aprovechar la ventaja de la inyección automática de constructores de contenedores de ID. Asumiendo que
la clase controlador depende de otros objetos, tales como un servicio de reservas de hotel. Se puede declarar una
dependencia a través de un parámetro del constructor y permitir al contenedor de ID resolverla por nosotros.
```php
namespace app\controllers;
use yii\web\Controller;
use app\components\BookingInterface;
class HotelController extends Controller
{
protected $bookingService;
public function __construct($id, $module, BookingInterface $bookingService, $config = [])
{
$this->bookingService = $bookingService;
parent::__construct($id, $module, $config);
}
}
```
Si se accede al controlador desde el navegador, veremos un error advirtiendo que `BookingInterface` no puede ser
instanciada. Esto se debe a que necesitamos indicar al contenedor de ID como tratar con esta dependencia:
```php
\Yii::$container->set('app\components\BookingInterface', 'app\components\BookingService');
```
Ahora si se accede al contenedor nuevamente, se creará una instancia de `app\components\BookingService` y se inyectará
a como tercer parámetro al constructor del controlador.
Cuando Registrar Dependencias
-----------------------------
El registro de dependencias debe hacerse lo antes posible debido a que las dependencias se necesitan cuando se crean
nuevos objetos. A continuación se listan practicas recomendadas:
* Siendo desarrolladores de una aplicación, podemos registrar dependencias en el
[script de entrada](structure-entry-scripts.md) o en un script incluido en el script de entrada.
* Siendo desarrolladores de una [extension](structure-extensions.md) redistribuible, podemos registrar dependencias en
la clase de boostraping de la extensión.
Resumen
-------
Tanto la inyección de dependencias como el [localizador de servicios](concept-service-locator.md) son patrones de
diseño populares que permiten construir software con acoplamiento flexible y más fácil de testear. Se recomienda
encarecida la lectura del articulo de [Martin](https://martinfowler.com/articles/injection.html) para obtener una mejor
comprensión de la inyección de dependencias y de la localización de servicios.
Yii implementa su propio [localizador de servicios](concept-service-locator.md) por encima del contenedor de ID.
Cuando un localizador de servicios intenta crear una nueva instancia de objeto, se desviará la llamada al contenedor
de ID. Este último resolverá las dependencias automáticamente como se ha descrito anteriormente.
---
### Guide Es Concept Events (`docs/guide-es/concept-events.md`)
Eventos
=======
Los eventos permiten inyectar código dentro de otro código existente en ciertos puntos de ejecución. Se pueden adjuntar
código personalizado a un evento, cuando se lance (triggered), el código se ejecutará automáticamente. Por ejemplo, un
objeto mailer puede lanzar el evento `messageSent` cuando se envía un mensaje correctamente. Si se quiere rastrear
el correcto envío del mensaje, se puede, simplemente, añadir un código de seguimiento al evento `messageSent`.
Yii introduce una clase base [[yii\base\Component]] para soportar eventos. Si una clase necesita lanzar un evento,
este debe extender a [[yii\base\Component]] o a una clase hija.
Gestor de Eventos
-----------------
Un gestor de eventos es una
[llamada de retorno PHP (PHP callback)](https://www.php.net/manual/es/language.types.callable.php) que se ejecuta cuando se
lanza el evento al que corresponde. Se puede usar cualquier llamada de retorno de las enumeradas a continuación:
- una función de PHP global especificada como una cadena de texto (sin paréntesis), ej. `'trim'`;
- un método de objeto especificado como un array de un objeto y un nombre de método como una cadena de texto
(sin paréntesis), ej. `[$object, 'methodNAme']`;
- un método de clase estático especificado como un array de un nombre de clase y un método como una cadena de texto
(sin paréntesis), ej. `[$class, 'methodName']`;
- una función anónima, ej. `function ($event) { ... }`.
La firma de un gestor de eventos es:
```php
function ($event) {
// $event es un objeto de yii\base\Event o de una clase hija
}
```
Un gestor de eventos puede obtener la siguiente información acerca de un evento ya sucedido mediante el parámetro
`$event`:
- [[yii\base\Event::name|nombre del evento]]
- [[yii\base\Event::sender|evento enviando]]: el objeto desde el que se ha ejecutado `trigger()`
- [[yii\base\Event::data|custom data]]: los datos que se proporcionan al adjuntar el gestor de eventos
(se explicará más adelante)
Añadir Gestores de Eventos
--------------------------
Se puede añadir un gestor a un evento llamando al método [[yii\base\Component::on()]]. Por ejemplo:
```php
$foo = new Foo;
// este gestor es una función global
$foo->on(Foo::EVENT_HELLO, 'function_name');
// este gestor es un método de objeto
$foo->on(Foo::EVENT_HELLO, [$object, 'methodName']);
// este gestor es un método de clase estática
$foo->on(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName']);
// este gestor es una función anónima
$foo->on(Foo::EVENT_HELLO, function ($event) {
// event handling logic
});
```
También se pueden adjuntar gestores de eventos mediante [configuraciones](concept-configurations.md). Se pueden
encontrar más de talles en la sección [Configuraciones](concept-configurations.md#configuration-format).
Cuando se adjunta un gestor de eventos, se pueden proporcionar datos adicionales como tercer parámetro de
[[yii\base\Component::on()]]. El gestor podrá acceder a los datos cuando se lance el evento y se ejecute el gestor.
Por ejemplo:
```php
// El siguiente código muestra "abc" cuando se lanza el evento
// ya que $event->data contiene los datos enviados en el tercer parámetro de "on"
$foo->on(Foo::EVENT_HELLO, 'function_name', 'abc');
function function_name($event) {
echo $event->data;
}
```
Ordenación de Gestores de Eventos
---------------------------------
Se puede adjuntar uno o más gestores a un único evento. Cuando se lanza un evento, se ejecutarán los gestores adjuntos
en el orden que se hayan añadido al evento. Si un gestor necesita parar la invocación de los gestores que le siguen,
se puede establecer la propiedad [[yii\base\Event::handled]] del parámetro `$event` para que sea `true`:
```php
$foo->on(Foo::EVENT_HELLO, function ($event) {
$event->handled = true;
});
```
De forma predeterminada, cada nuevo gestor añadido se pone a la cola de la lista de gestores del evento. Por lo tanto,
el gestor se ejecutará en el último lugar cuando se lance el evento. Para insertar un nuevo gestor al principio de la
cola de gestores para que sea ejecutado primero, se debe llamar a [[yii\base\Component::on()]], pasando al cuarto
parámetro `$append` el valor `false`:
```php
$foo->on(Foo::EVENT_HELLO, function ($event) {
// ...
}, $data, false);
```
Lanzamiento de Eventos
----------------------
Los eventos se lanzan llamando al método [[yii\base\Component::trigger()]]. El método requiere un *nombre de evento*,
y de forma opcional un objeto de evento que describa los parámetros que se enviarán a los gestores de eventos. Por
ejemplo:
```php
namespace app\components;
use yii\base\Component;
use yii\base\Event;
class Foo extends Component
{
const EVENT_HELLO = 'hello';
public function bar()
{
$this->trigger(self::EVENT_HELLO);
}
}
```
Con el código anterior, cada llamada a `bar()` lanzará un evento llamado `hello`
> Tip: Se recomienda usar las constantes de clase para representar nombres de eventos. En el anterior ejemplo, la
constante `EVENT_HELLO` representa el evento `hello`. Este enfoque proporciona tres beneficios. Primero, previene
errores tipográficos. Segundo, puede hacer que los IDEs reconozcan los eventos en las funciones de auto-completado.
Tercero, se puede ver que eventos soporta una clase simplemente revisando la declaración de constantes.
A veces cuando se lanza un evento se puede querer pasar información adicional al gestor de eventos. Por ejemplo, un
mailer puede querer enviar la información del mensaje para que los gestores del evento `messageSent` para que los
gestores puedan saber las particularidades del mensaje enviado. Para hacerlo, se puede proporcionar un objeto de tipo
evento como segundo parámetro al método [[yii\base\Component::trigger()]]. El objeto de tipo evento debe ser una
instancia de la clase [[yii\base\Event]] o de su clase hija. Por ejemplo:
```php
namespace app\components;
use yii\base\Component;
use yii\base\Event;
class MessageEvent extends Event
{
public $message;
}
class Mailer extends Component
{
const EVENT_MESSAGE_SENT = 'messageSent';
public function send($message)
{
// ...enviando $message...
$event = new MessageEvent;
$event->message = $message;
$this->trigger(self::EVENT_MESSAGE_SENT, $event);
}
}
```
Cuando se lanza el método [[yii\base\Component::trigger()]], se ejecutarán todos los gestores adjuntos al evento.
Desadjuntar Gestores de Evento
------------------------------
Para desadjuntar un gestor de un evento, se puede ejecutar el método [[yii\base\Component::off()]]. Por ejemplo:
```php
// el gestor es una función global
$foo->off(Foo::EVENT_HELLO, 'function_name');
// el gestor es un método de objeto
$foo->off(Foo::EVENT_HELLO, [$object, 'methodName']);
// el gestor es un método estático de clase
$foo->off(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName']);
// el gestor es una función anónima
$foo->off(Foo::EVENT_HELLO, $anonymousFunction);
```
Tenga en cuenta que en general no se debe intentar desadjuntar las funciones anónimas a no ser que se almacene donde
se ha adjuntado al evento. En el anterior ejemplo, se asume que la función anónima se almacena como variable
`$anonymousFunction`.
Para desadjuntar TODOS los gestores de un evento, se puede llamar [[yii\base\Component::off()]] sin el segundo
parámetro:
```php
$foo->off(Foo::EVENT_HELLO);
```
Nivel de Clase (Class-Level) Gestores de Eventos
------------------------------------------------
En las subsecciones anteriores se ha descrito como adjuntar un gestor a un evento a *nivel de instancia*. A veces, se
puede querer que un gestor responda todos los eventos de *todos* las instancias de una clase en lugar de una instancia
especifica. En lugar de adjuntar un gestor de eventos a una instancia, se puede adjuntar un gestor a *nivel de clase*
llamando al método estático [[yii\base\Event::on()]].
Por ejemplo, un objeto de tipo [Active Record](db-active-record.md) lanzará un evento
[[yii\db\BaseActiveRecord::EVENT_AFTER_INSERT|EVENT_AFTER_INSERT]] cada vez que inserte un nuevo registro en la base
de datos. Para poder registrar las inserciones efectuadas por *todos* los objetos
[Active Record](db-active-record.md), se puede usar el siguiente código:
```php
use Yii;
use yii\base\Event;
use yii\db\ActiveRecord;
Event::on(ActiveRecord::class, ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
Yii::debug(get_class($event->sender) . ' is inserted');
});
```
Se invocará al gestor de eventos cada vez que una instancia de [[yii\db\ActiveRecord|ActiveRecord]], o de uno de sus
clases hijas, lance un evento de tipo [[yii\db\BaseActiveRecord::EVENT_AFTER_INSERT|EVENT_AFTER_INSERT]]. Se puede
obtener el objeto que ha lanzado el evento mediante `$event->sender` en el gestor.
Cuando un objeto lanza un evento, primero llamará los gestores a nivel de instancia, y a continuación los gestores a
nivel de clase.
Se puede lanzar un evento de tipo *nivel de clase* llamando al método estático [[yii\base\Event::trigger()]]. Un
evento de nivel de clase no se asocia a un objeto en particular. Como resultado, esto provocará solamente la
invocación de los gestores de eventos a nivel de clase.
```php
use yii\base\Event;
Event::on(Foo::class, Foo::EVENT_HELLO, function ($event) {
var_dump($event->sender); // displays "null"
});
Event::trigger(Foo::class, Foo::EVENT_HELLO);
```
Tenga en cuenta que en este caso, el `$event->sender` hace referencia al nombre de la clase que lanza el evento en
lugar de a la instancia del objeto.
> Note: Debido a que los gestores a nivel de clase responderán a los eventos lanzados por cualquier instancia de la
clase, o cualquier clase hija, se debe usar con cuidado, especialmente en las clases de bajo nivel (low-level), tales
como [[yii\base\BaseObject]].
Para desadjuntar un gestor de eventos a nivel de clase, se tiene que llamar a [[yii\base\Event::off()]]. Por ejemplo:
```php
// desadjunta $handler
Event::off(Foo::class, Foo::EVENT_HELLO, $handler);
// desadjunta todos los gestores de Foo::EVENT_HELLO
Event::off(Foo::class, Foo::EVENT_HELLO);
```
Eventos Globales
----------------
Yii soporta los llamados *eventos globales*, que en realidad es un truco basado en el gestor de eventos descrito
anteriormente. El evento global requiere un Singleton globalmente accesible, tal como la instancia de
[aplicación](structure-applications.md) en si misma.
Para crear un evento global, un evento remitente (event sender) llama al método `trigger()` del Singleton para lanzar
el evento, en lugar de llamar al propio método `trigger()` del remitente. De forma similar, los gestores de eventos se
adjuntan al evento del Singleton. Por ejemplo:
```php
use Yii;
use yii\base\Event;
use app\components\Foo;
Yii::$app->on('bar', function ($event) {
echo get_class($event->sender); // muestra "app\components\Foo"
});
Yii::$app->trigger('bar', new Event(['sender' => new Foo]));
```
Un beneficio de usar eventos globales es que no se necesita un objeto cuando se adjuntan gestores a un evento para que
sean lanzados por el objeto. En su lugar, los gestores adjuntos y el lanzamiento de eventos se efectúan en el
Singleton (ej. la instancia de la aplicación).
Sin embargo, debido a que los `namespaces` de los eventos globales son compartidos por todas partes, se les deben
asignar nombres bien pensados, como puede ser la introducción de algún `namespace`
(ej. "frontend.mail.sent", "backend.mail.sent").
---
### Guide Es Concept Properties (`docs/guide-es/concept-properties.md`)
Propiedades
===========
En PHP, las variables miembro de clases también llamadas *propiedades*, son parte de la definición de la clase, y se
usan para representar el estado de una instancia de la clase (ej. para diferenciar una instancia de clase de otra).
A la práctica, a menudo, se puede querer gestionar la lectura o escritura de las propiedades de algunos momentos. Por
ejemplo, se puede querer eliminar los espacios en blanco (trim) de una cadena de texto cada vez que esta se asigne a
una propiedad de tipo `label`. Se *podría* usar el siguiente código para realizar esta tarea:
```php
$object->label = trim($label);
```
La desventaja del código anterior es que se tendría que ejecutar `trim()` en todas las partes del código que pudieran
establecer la propiedad `label`. Si en el futuro, la propiedad `label` tiene que seguir otro funcionamiento, como por
ejemplo que la primera letra tiene que estar en mayúsculas, se tendrán que modificar todas las secciones de código que
asignen el valor a la propiedad `label`. La repetición de código conlleva a bugs, y es una practica que se tiene que
evitar en la medida de lo posible.
Para solventar este problema, Yii introduce la clase base llamada [[yii\base\BaseObject]] que da soporte a la definición
de propiedades basada en los métodos de clase *getter* y *setter*. Si una clase necesita más funcionalidad, debe
extender a la clase [[yii\base\BaseObject]] o a alguna de sus hijas.
> Info: Casi todas las clases del núcleo (core) en el framework Yii extienden a [[yii\base\BaseObject]] o a una de
sus clases hijas. Esto significa que siempre que se encuentre un getter o un setter en una clase del núcleo, se
puede utilizar como una propiedad.
Un método getter es un método cuyo nombre empieza por la palabra `get`: un metodo setter empieza por `set`. El nombre
añadido detrás del prefijo `get` o `set` define el nombre de la propiedad. Por ejemplo, un getter `getLabel()` y/o un
setter `setLabel()` definen la propiedad `label`, como se muestra a continuación:
```php
namespace app\components;
use yii\base\BaseObject;
class Foo extends BaseObject
{
private $_label;
public function getLabel()
{
return $this->_label;
}
public function setLabel($value)
{
$this->_label = trim($value);
}
}
```
(Para ser claros, los métodos getter y setter crean la propiedad `label`, que en este caso hace una referencia interna
al nombre de atributo privado `_label`.)
Las propiedades definidas por los getter y los setters se pueden usar como variables de clase miembro. La principal
diferencia radica en que cuando esta propiedad se lea, se ejecutará su correspondiente método getter; cuando se asigne
un valor a la propiedad, se ejecutará el correspondiente método setter. Por ejemplo:
```php
// equivalente a $label = $object->getLabel();
$label = $object->label;
// equivalente a $object->setLabel('abc');
$object->label = 'abc';
```
Una propiedad definida por un getter sin un setter es de tipo *sólo lectura*. Si se intenta asignar un valor a esta
propiedad se producirá una excepción de tipo [[yii\base\InvalidCallException|InvalidCallException]]. Del mismo modo
que una propiedad definida con un setter pero sin getter será de tipo *sólo escritura*, cualquier intento de lectura
de esta propiedad producirá una excepción. No es común tener variables de tipo sólo escritura.
Hay varias reglas especiales y limitaciones en las propiedades definidas mediante getters y setters:
* Los nombres de estas propiedades son *case-insensitive*. Por ejemplo, `$object->label` y `$object->Label` son la
misma. Esto se debe a que los nombres de los métodos en PHP son case-insensitive.
* Si el nombre de una propiedad de este tipo es igual al de una variable miembro de la clase, la segunda tendrá
prioridad. Por ejemplo, si la anterior clase `Foo` tiene la variable miembro `label`, entonces la asignación
`$object->label = 'abc'` afectará a la *variable miembro* 'label'; no se ejecutará el método setter `setLabel()`.
* Estas variables no soportan la visibilidad. No hay diferencia en definir los métodos getter o setter en una
propiedad public, protected, o private.
* Las propiedades sólo se pueden definir por getters y setters *no estáticos*. Los métodos estáticos no se tratarán de
la misma manera.
Volviendo de nuevo al problema descrito al principio de la guía, en lugar de ejecutar `trim()` cada vez que se asigne
un valor a `label`, ahora `trim()` sólo necesita ser invocado dentro del setter `setLabel()`. I si se tiene que añadir
un nuevo requerimiento, para que `label` empiece con una letra mayúscula, se puede modificar rápidamente el método `
setLabel()` sin tener que modificar más secciones de código. El cambio afectará a cada asignación de `label`.
---
### Guide Es Concept Service Locator (`docs/guide-es/concept-service-locator.md`)
Localizador de Servicios
========================
Un localizador de servicios es un objeto que sabe cómo proporcionar todo tipo de servicios (o componentes) que puede necesitar una aplicación. Dentro de un localizador de servicios, existe en cada componente como una única instancia, únicamente identificado por un ID. Se utiliza el ID para recuperar un componente desde el localizador de servicios.
En Yii, un localizador de servicio es simplemente una instancia de [[yii\di\ServiceLocator]], o de una clase hija.
El localizador de servicio más utilizado en Yii es el objeto *aplicación*, que se puede acceder a través de `\Yii::$app`. Los servicios que prestá son llamadas *componentes de la aplicación*, como los componentes `request`, `response`, and `urlManager`. Usted puede configurar estos componentes, o incluso cambiarlos por sus propias implementaciones fácilmente a través de la funcionalidad proporcionada por el localizador de servicios.
Además del objeto de aplicación, cada objeto módulo es también un localizador de servicios.
Para utilizar un localizador de servicios, el primer paso es registrar los componentes de la misma. Un componente se puede registrar a través de [[yii\di\ServiceLocator::set()]]. El código siguiente muestra diferentes maneras de registrarse componentes:
```php
use yii\di\ServiceLocator;
use yii\caching\FileCache;
$locator = new ServiceLocator;
// register "cache" using a class name that can be used to create a component
$locator->set('cache', 'yii\caching\ApcCache');
// register "db" using a configuration array that can be used to create a component
$locator->set('db', [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=demo',
'username' => 'root',
'password' => '',
]);
// register "search" using an anonymous function that builds a component
$locator->set('search', function () {
return new app\components\SolrService;
});
// register "pageCache" using a component
$locator->set('pageCache', new FileCache);
```
Una vez que el componente se ha registrado, usted puede acceder a él utilizando su ID, en una de las dos formas siguientes:
```php
$cache = $locator->get('cache');
// or alternatively
$cache = $locator->cache;
```
Como puede observarse, [[yii\di\ServiceLocator]] le permite acceder a un componente como una propiedad utilizando el ID de componente. Cuando acceda a un componente, por primera vez, [[yii\di\ServiceLocator]] utilizará la información de registro de componente para crear una nueva instancia del componente y devolverlo. Más tarde, si se accede de nuevo al componente, el localizador de servicio devolverá la misma instancia.
Usted puede utilizar [[yii\di\ServiceLocator::has()]] para comprobar si un ID de componente ya ha sido registrada.
Si llama [[yii\di\ServiceLocator::get()]] con una identificación válida, se produce una excepción.
Debido a que los localizadores de servicios a menudo se crean con [configuraciones](concept-configurations.md), se proporciona una propiedad que puede escribir el nombre [[yii\di\ServiceLocator::setComponents()|components]]. Esto le permite configurar y registrar varios componentes a la vez. El siguiente código muestra un arreglo de configuración que se puede utilizar para configurar una aplicación, al mismo tiempo que el registro de la "db", "cache" y "buscar" componentes:
```php
return [
// ...
'components' => [
'db' => [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=demo',
'username' => 'root',
'password' => '',
],
'cache' => 'yii\caching\ApcCache',
'search' => function () {
return new app\components\SolrService;
},
],
];
```
---
### Guide Es Db Dao (`docs/guide-es/db-dao.md`)
Objetos de Acceso a Bases de Datos
==================================
Construido sobre [PDO](https://www.php.net/manual/es/book.pdo.php), Yii DAO (Objetos de Acceso a Bases de Datos) proporciona una
API orientada a objetos para el acceso a bases de datos relacionales. Es el fundamento para otros métodos de acceso a bases de datos
más avanzados, incluyendo el [constructor de consultas](db-query-builder.md) y [active record](db-active-record.md).
Al utilizar Yii DAO, principalmente vas a tratar con SQLs planos y arrays PHP. Como resultado, esta es la manera más eficiente
de acceder a las bases de datos. Sin embargo, como la sintaxis puede variar para las diferentes bases de datos, utilizando
Yii DAO también significa que tienes que tienes que tomar un esfuerzo adicional para crear una aplicación de database-agnostic.
Yii DAO soporta las siguientes bases de datos:
- [MySQL](https://www.mysql.com/)
- [MariaDB](https://mariadb.com/)
- [SQLite](https://sqlite.org/)
- [PostgreSQL](https://www.postgresql.org/): versión 8.4 o superior.
- [CUBRID](https://www.cubrid.org/): versión 9.3 o superior.
- [Oracle](https://www.oracle.com/database/)
- [MSSQL](https://www.microsoft.com/en-us/sqlserver/default.aspx): versión 2008 o superior.
## Creando Conexiones DB
Para acceder a una base de datos, primero necesitas conectarte a tu bases de datos mediante la creación
de una instancia de [[yii\db\Connection]]:
```php
$db = new yii\db\Connection([
'dsn' => 'mysql:host=localhost;dbname=example',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
]);
```
Debido a una conexión DB a menudo necesita ser accedido en diferentes lugares, una práctica común es
configurarlo en términos de un [componente de aplicación](structure-application-components.md) como
se muestra a continuación:
```php
return [
// ...
'components' => [
// ...
'db' => [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=example',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
],
],
// ...
];
```
Puedes acceder a la conexión DB mediante la expresión `Yii::$app->db`.
> Tip: Puedes configurar múltiples componentes de aplicación DB si tu aplicación necesita acceder a múltiples bases de datos.
Cuando configuras una conexión DB, deberías siempre especificar el Nombre de Origen de Datos (DSN) mediante la
propiedad [[yii\db\Connection::dsn|dsn]]. El formato del DSN varia para cada diferente base de datos. Por favor consulte el
[manual de PHP](https://www.php.net/manual/es/function.PDO-construct.php) para más detalles. Abajo están algunos ejemplos:
* MySQL, MariaDB: `mysql:host=localhost;dbname=mydatabase`
* SQLite: `sqlite:/path/to/database/file`
* PostgreSQL: `pgsql:host=localhost;port=5432;dbname=mydatabase`
* CUBRID: `cubrid:dbname=demodb;host=localhost;port=33000`
* MS SQL Server (mediante sqlsrv driver): `sqlsrv:Server=localhost;Database=mydatabase`
* MS SQL Server (mediante dblib driver): `dblib:host=localhost;dbname=mydatabase`
* MS SQL Server (mediante mssql driver): `mssql:host=localhost;dbname=mydatabase`
* Oracle: `oci:dbname=//localhost:1521/mydatabase`
Nota que si estás conectándote con una base de datos mediante ODBC, deberías configurar la propiedad [[yii\db\Connection::driverName]]
para que Yii pueda conocer el tipo de base de datos actual. Por ejemplo,
```php
'db' => [
'class' => 'yii\db\Connection',
'driverName' => 'mysql',
'dsn' => 'odbc:Driver={MySQL};Server=localhost;Database=test',
'username' => 'root',
'password' => '',
],
```
Además de la propiedad [[yii\db\Connection::dsn|dsn]], a menudo es necesario configurar el [[yii\db\Connection::username|username]]
y [[yii\db\Connection::password|password]]. Por favor consulta [[yii\db\Connection]] para ver la lista completa de propiedades configurables.
> Info: Cuando se crea una instancia de conexión DB, la conexión actual a la base de datos no se establece hasta que
ejecutes el primer SQL o llames explícitamente al método [[yii\db\Connection::open()|open()]].
## Ejecutando Consultas SQL
Una vez tienes instanciada una conexión a la base de datos, se pueden ejecutar consultas SQL tomando
los siguientes pasos:
1. Crea un [[yii\db\Command]] con SQL plano;
2. Vincula parámetros (opcional);
3. Llama a uno de los métodos de ejecución SQL con [[yii\db\Command]].
El siguiente ejemplo muestra varias maneras de obtener datos de una base de datos:
```php
$db = new yii\db\Connection(...);
// retorna un conjunto de filas. Cada fila es un array asociativo de columnas de nombres y valores.
// un array vacío es retornado si no hay resultados
$posts = $db->createCommand('SELECT * FROM post')
->queryAll();
// retorna una sola fila (la primera fila)
// `false` es retornado si no hay resultados
$post = $db->createCommand('SELECT * FROM post WHERE id=1')
->queryOne();
// retorna una sola columna (la primera columna)
// un array vacío es retornado si no hay resultados
$titles = $db->createCommand('SELECT title FROM post')
->queryColumn();
// retorna un escalar
// `false` es retornado si no hay resultados
$count = $db->createCommand('SELECT COUNT(*) FROM post')
->queryScalar();
```
> Note: Para preservar la precisión, los datos obtenidos de las bases de datos son todos representados como cadenas, incluso si el tipo de columna correspondiente
a la base de datos es numérico.
> Tip: Si necesitas ejecutar una consulta SQL inmediatamente después de establecer una conexión (ej., para establecer una zona horaria o un conjunto de caracteres),
> puedes hacerlo con el evento [[yii\db\Connection::EVENT_AFTER_OPEN]]. Por ejemplo,
>
```php
return [
// ...
'components' => [
// ...
'db' => [
'class' => 'yii\db\Connection',
// ...
'on afterOpen' => function($event) {
// $event->sender se refiere a la conexión DB
$event->sender->createCommand("SET time_zone = 'UTC'")->execute();
}
],
],
// ...
];
```
### Parámetros Vinculados (Binding Parameters)
Cuando creamos un comando DB para un SQL con parámetros, nosotros deberíamos casi siempre aprovechar el uso de los parámetros vinculados
para prevenir los ataques de inyección de SQL. Por ejemplo,
```php
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status')
->bindValue(':id', $_GET['id'])
->bindValue(':status', 1)
->queryOne();
```
En la sentencia SQL, puedes incrustar uno o múltiples parámetros placeholders (ej. `:id` en el ejemplo anterior). Un parámetro
placeholder debería ser una cadena que empiece con dos puntos. A continuación puedes llamar a uno de los siguientes métodos para
unir los valores de los parámetros vinculados:
* [[yii\db\Command::bindValue()|bindValue()]]: une un solo parámetro
* [[yii\db\Command::bindValues()|bindValues()]]: une múltiples parámetros en una sola llamada
* [[yii\db\Command::bindParam()|bindParam()]]: similar a [[yii\db\Command::bindValue()|bindValue()]] pero también
soporta las referencias de parámetros vinculados.
El siguiente ejemplo muestra formas alternativas de vincular parámetros:
```php
$params = [':id' => $_GET['id'], ':status' => 1];
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status')
->bindValues($params)
->queryOne();
$post = $db->createCommand('SELECT * FROM post WHERE id=:id AND status=:status', $params)
->queryOne();
```
La vinculación parámetros es implementada mediante [sentencias preparadas (prepared statements)](https://www.php.net/manual/es/mysqli.quickstart.prepared-statements.php).
Además de prevenir ataques de inyección de SQL, también puede mejorar el rendimiento preparando una sola vez una sentencia SQL y ejecutándola múltiples veces con diferentes
parámetros. Por ejemplo,
```php
$command = $db->createCommand('SELECT * FROM post WHERE id=:id');
$post1 = $command->bindValue(':id', 1)->queryOne();
$post2 = $command->bindValue(':id', 2)->queryOne();
```
Porque [[yii\db\Command::bindParam()|bindParam()]] soporta parámetros vinculados por referencias, el código de arriba también
puede ser escrito como lo siguiente:
```php
$command = $db->createCommand('SELECT * FROM post WHERE id=:id')
->bindParam(':id', $id);
$id = 1;
$post1 = $command->queryOne();
$id = 2;
$post2 = $command->queryOne();
```
Observe que vincula el placeholder a la variable `$id` antes de la ejecución, y entonces cambia el valor de esa variable
antes de cada subsiguiente ejecución (esto se hace a menudo con bucles). Ejecutando consultas de esta manera puede ser
bastante más eficiente que ejecutar una nueva consulta para cada valor diferente del parámetro.
### Ejecutando Consultas Non-SELECT
El método `queryXyz()` introducidos en las secciones previas todos tratan con consultas SELECT los cuales recogen los
datos de la base de datos. Para las consultas que no devuelven datos, deberías llamar a el método [[yii\db\Command::execute()]]
en su lugar. Por ejemplo,
```php
$db->createCommand('UPDATE post SET status=1 WHERE id=1')
->execute();
```
El método [[yii\db\Command::execute()]] retorna el número de filas afectadas por la ejecución SQL.
Para consultas INSERT, UPDATE y DELETE, en vez de escribir SQLs planos, puedes llamar a [[yii\db\Command::insert()|insert()]],
[[yii\db\Command::update()|update()]], [[yii\db\Command::delete()|delete()]], respectivamente, construyen los correspondientes
SQLs. Estos métodos entrecomillan adecuadamente las tablas y los nombres de columnas y los valores de los parámetros vinculados.
Por ejemplo,
```php
// INSERT (table name, column values)
$db->createCommand()->insert('user', [
'name' => 'Sam',
'age' => 30,
])->execute();
// UPDATE (table name, column values, condition)
$db->createCommand()->update('user', ['status' => 1], 'age > 30')->execute();
// DELETE (table name, condition)
$db->createCommand()->delete('user', 'status = 0')->execute();
```
Puedes también llamar a [[yii\db\Command::batchInsert()|batchInsert()]] para insertar múltiples filas de una sola vez,
que es mucho más eficiente que insertar una fila de cada vez:
```php
// table name, column names, column values
$db->createCommand()->batchInsert('user', ['name', 'age'], [
['Tom', 30],
['Jane', 20],
['Linda', 25],
])->execute();
```
## Entrecomillado de Tablas y Nombres de Columna
Al escribir código de database-agnostic, entrecomillar correctamente los nombres de las tablas y las columnas es a menudo
un dolor de cabeza porque las diferentes bases de datos tienen diferentes reglas para entrecomillar los nombres. Para
solventar este problema, puedes usar la siguiente sintaxis de entrecomillado introducido por Yii:
* `[[column name]]`: encierra con dobles corchetes el nombre de una columna que debe ser entrecomillado;
* `{{table name}}`: encierra con dobles llaves el nombre de una tabla que debe ser entrecomillado.
Yii DAO automáticamente convertirá tales construcciones en un SQL con los correspondientes entrecomillados de los nombres de las columnas o tablas.
Por ejemplo,
```php
// ejecuta esta SQL para MySQL: SELECT COUNT(`id`) FROM `employee`
$count = $db->createCommand("SELECT COUNT([[id]]) FROM {{employee}}")
->queryScalar();
```
### Usando Prefijos de Tabla
Si la mayoría de tus tablas de BD utilizan algún prefijo común en sus tablas, puedes usar la función de prefijo de tabla soportado
por Yii DAO.
Primero, especifica el prefijo de tabla mediante la propiedad [[yii\db\Connection::tablePrefix]]:
```php
return [
// ...
'components' => [
// ...
'db' => [
// ...
'tablePrefix' => 'tbl_',
],
],
];
```
Luego en tu código, siempre que lo necesites para hacer referencia a una tabla cuyo nombre tiene un prefijo, utiliza la sintaxis
`{{%table name}}`. El carácter porcentaje se sustituye con el prefijo de la tabla que has especificado en la configuración de
la conexión DB. Por ejemplo,
```php
// ejecuta esta SQL para MySQL: SELECT COUNT(`id`) FROM `tbl_employee`
$count = $db->createCommand("SELECT COUNT([[id]]) FROM {{%employee}}")
->queryScalar();
```
## Realización de Transacciones
Cuando se ejecutan múltiples consultas relacionadas en una secuencia, puede que se tengan que envolver en una
transacción para asegurar la integridad de los datos y la consistencia de tu base de datos. Si cualquiera de las consultas
falla, la base de datos debe ser revertida al estado anterior como si ninguna de estas consultas se haya ejecutado.
El siguiente código muestra una manera típica de usar transacciones:
```php
$db->transaction(function($db) {
$db->createCommand($sql1)->execute();
$db->createCommand($sql2)->execute();
// ... ejecutando otras sentencias SQL
});
```
El código de arriba es equivalente a lo siguiente:
```php
$transaction = $db->beginTransaction();
try {
$db->createCommand($sql1)->execute();
$db->createCommand($sql2)->execute();
// ... ejecutando otras sentencias SQL
$transaction->commit();
} catch(\Exception $e) {
$transaction->rollBack();
throw $e;
}
```
Al llamar al método [[yii\db\Connection::beginTransaction()|beginTransaction()]], se inicia una nueva transacción.
La transacción se representa como un objeto [[yii\db\Transaction]] almacenado en la variable `$transaction`. Luego,
las consultas que se ejecutan están encerrados en un bloque `try...catch...`. Si todas las consultas son ejecutadas satisfactoriamente,
el método [[yii\db\Transaction::commit()|commit()]] es llamado para confirmar la transacción. De lo contrario, una excepción
se disparará y se capturará, y el método [[yii\db\Transaction::rollBack()|rollBack()]] es llamado para revertir
los cambios hechos por las consultas antes de que fallara la consulta en la transacción.
### Especificando los Niveles de Aislamiento
Yii también soporta la configuración de [niveles de aislamiento] para tus transacciones. Por defecto, cuando comienza una nueva transacción,
utilizará el nivel de aislamiento definido por tu sistema de base de datos. Se puede sobrescribir el nivel de aislamiento por defecto de la
siguiente manera,
```php
$isolationLevel = \yii\db\Transaction::REPEATABLE_READ;
$db->transaction(function ($db) {
....
}, $isolationLevel);
// or alternatively
$transaction = $db->beginTransaction($isolationLevel);
```
Yii proporciona cuatro constantes para los niveles de aislamiento más comunes:
- [[\yii\db\Transaction::READ_UNCOMMITTED]] - el nivel más bajo, pueden ocurrir lecturas Dirty, lecturas
Non-repeatable y Phantoms.
- [[\yii\db\Transaction::READ_COMMITTED]] - evita lecturas Dirty.
- [[\yii\db\Transaction::REPEATABLE_READ]] - evita lecturas Dirty y lecturas Non-repeatable.
- [[\yii\db\Transaction::SERIALIZABLE]] - el nivel más fuerte, evita todos los problemas nombrados anteriormente.
Además de usar las constantes de arriba para especificar los niveles de aislamiento, puedes también usar cadenas con
una sintaxis valida soportada por el DBMS que estés usando. Por ejemplo, en PostgreSQL, puedes utilizar `SERIALIZABLE READ ONLY DEFERRABLE`.
Tenga en cuenta que algunos DBMS permiten configuraciones de niveles de aislamiento solo a nivel de conexión. Las transacciones subsiguientes
recibirá el mismo nivel de aislamiento , incluso si no se especifica ninguna. Al utilizar esta característica
es posible que necesites ajustar el nivel de aislamiento para todas las transacciones de forma explícitamente para evitar conflictos
en las configuraciones.
En el momento de escribir esto, solo MSSQL y SQLite serán afectadas.
> Note: SQLite solo soporta dos niveles de aislamiento, por lo que solo se puede usar `READ UNCOMMITTED` y
`SERIALIZABLE`. El uso de otros niveles causará el lanzamiento de una excepción.
> Note: PostgreSQL no permite configurar el nivel de aislamiento antes que la transacción empiece por lo que no se
puede especificar el nivel de aislamiento directamente cuando empieza la transacción. Se tiene que llamar a
[[yii\db\Transaction::setIsolationLevel()]] después de que la transacción haya empezado.
[isolation levels]: https://es.wikipedia.org/wiki/Aislamiento_(ACID)#Niveles_de_aislamiento
### Transacciones Anidadas
Si tu DBMS soporta Savepoint, puedes anidar múltiples transacciones como a continuación:
```php
$db->transaction(function ($db) {
// outer transaction
$db->transaction(function ($db) {
// inner transaction
});
});
```
O alternativamente,
```php
$outerTransaction = $db->beginTransaction();
try {
$db->createCommand($sql1)->execute();
$innerTransaction = $db->beginTransaction();
try {
$db->createCommand($sql2)->execute();
$innerTransaction->commit();
} catch (Exception $e) {
$innerTransaction->rollBack();
}
$outerTransaction->commit();
} catch (Exception $e) {
$outerTransaction->rollBack();
}
```
## Replicación y División Lectura-Escritura
Muchos DBMS soportan [replicación de bases de datos](https://es.wikipedia.org/wiki/Replicaci%C3%B3n_(inform%C3%A1tica)) para tener
una mejor disponibilidad de la base de datos y un mejor tiempo de respuesta del servidor. Con la replicación de bases
de datos, los datos están replicados en los llamados *servidores maestros* (master servers) y *servidores esclavos*
(slave servers). Todas las escrituras y actualizaciones deben hacerse en el servidor maestro, mientras que las lecturas
se efectuarán en los servidores esclavos.
Para aprovechar las ventajas de la replicación de la base de datos y lograr una división de lecuta-escritura, se puede configurar
el componente [[yii\db\Connection]] como se muestra a continuación:
```php
[
'class' => 'yii\db\Connection',
// configuración para el maestro
'dsn' => 'dsn for master server',
'username' => 'master',
'password' => '',
// configuración para los esclavos
'slaveConfig' => [
'username' => 'slave',
'password' => '',
'attributes' => [
// utiliza un tiempo de espera de conexión más pequeña
PDO::ATTR_TIMEOUT => 10,
],
],
// listado de configuraciones de esclavos
'slaves' => [
['dsn' => 'dsn for slave server 1'],
['dsn' => 'dsn for slave server 2'],
['dsn' => 'dsn for slave server 3'],
['dsn' => 'dsn for slave server 4'],
],
]
```
La configuración anterior especifica una configuración con un único maestro y múltiples esclavos. Uno de los esclavos
se conectará y se usará para ejecutar consultas de lectura, mientras que el maestro se usará para realizar consultas de
escritura. De este modo la división de lectura-escritura se logra automáticamente con esta configuración, Por ejemplo,
```php
// crea una instancia de Connection usando la configuración anterior
$db = Yii::createObject($config);
// consulta contra uno de los esclavos
$rows = $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
// consulta contra el maestro
$db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute();
```
> Info: Las consultas realizadas llamando a [[yii\db\Command::execute()]] se consideran consultas de escritura,
mientras que todas las demás se ejecutan mediante alguno de los métodos "query" de [[yii\db\Command]] son consultas
de lectura. Se puede obtener la conexión de esclavo activa mediante `$db->slave`.
El componente `Connection` soporta el balanceo de carga y la conmutación de errores entre esclavos. Cuando se realiza
una consulta de lectura por primera vez, el componente `Connection` elegirá un esclavo aleatorio e intentará realizar
una conexión a este. Si el esclavo se encuentra "muerto", se intentará con otro. Si no está disponible ningún esclavo, se conectará al maestro. Configurando una [[yii\db\Connection::serverStatusCache|server status cache]], se recordarán los servidores
"muertos" por lo que no se intentará volver a conectar a ellos durante
[[yii\db\Connection::serverRetryInterval|certain period of time]].
> Info: En la configuración anterior, se especifica un tiempo de espera (timeout) de conexión de 10 segundos
para cada esclavo. Esto significa que si no se puede conectar a un esclavo en 10 segundos, este será considerado
como "muerto". Se puede ajustar el parámetro basado en el entorno actual.
También se pueden configurar múltiples maestros con múltiples esclavos. Por ejemplo,
```php
[
'class' => 'yii\db\Connection',
// configuracion habitual para los maestros
'masterConfig' => [
'username' => 'master',
'password' => '',
'attributes' => [
// utilizar un tiempo de espera de conexión más pequeña
PDO::ATTR_TIMEOUT => 10,
],
],
// listado de configuraciones de maestros
'masters' => [
['dsn' => 'dsn for master server 1'],
['dsn' => 'dsn for master server 2'],
],
// configuración habitual para esclavos
'slaveConfig' => [
'username' => 'slave',
'password' => '',
'attributes' => [
// utilizar un tiempo de espera de conexión más pequeña
PDO::ATTR_TIMEOUT => 10,
],
],
// listado de configuración de esclavos
'slaves' => [
['dsn' => 'dsn for slave server 1'],
['dsn' => 'dsn for slave server 2'],
['dsn' => 'dsn for slave server 3'],
['dsn' => 'dsn for slave server 4'],
],
]
```
La configuración anterior especifica dos maestros y cuatro esclavos. El componente `Connection` también da soporte al
balanceo de carga y la conmutación de errores entre maestros igual que hace con los esclavos. La diferencia es que
cuando no se encuentra ningún maestro disponible se lanza una excepción.
> Note: cuando se usa la propiedad [[yii\db\Connection::masters|masters]] para configurar uno o múltiples maestros, se
ignorarán todas las otras propiedades que especifiquen una conexión de base de datos
(ej. `dsn`, `username`, `password`), junto con el mismo objeto `Connection`.
Por defecto. las transacciones usan la conexión del maestro. Y dentro de una transacción, todas las operaciones de DB usarán
la conexión del maestro. Por ejemplo,
```php
// la transacción empieza con la conexión al maestro
$transaction = $db->beginTransaction();
try {
// las dos consultas se ejecutan contra el maestro
$rows = $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
$db->createCommand("UPDATE user SET username='demo' WHERE id=1")->execute();
$transaction->commit();
} catch(\Exception $e) {
$transaction->rollBack();
throw $e;
}
```
Si se quiere empezar la transacción con una conexión a un esclavo, se debe hacer explícitamente como se muestra a
continuación:
```php
$transaction = $db->slave->beginTransaction();
```
A veces, se puede querer forzar el uso de una conexión maestra para realizar una consulta de lectura. Se puede lograr
usando el método `useMaster()`:
```php
$rows = $db->useMaster(function ($db) {
return $db->createCommand('SELECT * FROM user LIMIT 10')->queryAll();
});
```
También se puede utilizar directamente estableciendo `$db->enableSlaves` a `false` para que se redirijan todas las
consultas a la conexión del maestro.
## Trabajando con Esquemas de Bases de Datos
Yii DAO proporciona todo un conjunto de métodos que permites manipular el esquema de tu base de datos, tal como
crear nuevas tablas, borrar una columna de una tabla, etc. Estos métodos son listados a continuación:
* [[yii\db\Command::createTable()|createTable()]]: crea una tabla
* [[yii\db\Command::renameTable()|renameTable()]]: renombra una tabla
* [[yii\db\Command::dropTable()|dropTable()]]: remueve una tabla
* [[yii\db\Command::truncateTable()|truncateTable()]]: remueve todas las filas de una tabla
* [[yii\db\Command::addColumn()|addColumn()]]: añade una columna
* [[yii\db\Command::renameColumn()|renameColumn()]]: renombra una columna
* [[yii\db\Command::dropColumn()|dropColumn()]]: remueve una columna
* [[yii\db\Command::alterColumn()|alterColumn()]]: altera una columna
* [[yii\db\Command::addPrimaryKey()|addPrimaryKey()]]: añade una clave primaria
* [[yii\db\Command::dropPrimaryKey()|dropPrimaryKey()]]: remueve una clave primaria
* [[yii\db\Command::addForeignKey()|addForeignKey()]]: añade una clave ajena
* [[yii\db\Command::dropForeignKey()|dropForeignKey()]]: remueve una clave ajena
* [[yii\db\Command::createIndex()|createIndex()]]: crea un indice
* [[yii\db\Command::dropIndex()|dropIndex()]]: remueve un indice
Estos métodos puedes ser usados como se muestra a continuación:
```php
// CREATE TABLE
$db->createCommand()->createTable('post', [
'id' => 'pk',
'title' => 'string',
'text' => 'text',
]);
```
También puedes recuperar la información de definición de una tabla a través
del método [[yii\db\Connection::getTableSchema()|getTableSchema()]] de una conexión DB. Por ejemplo,
```php
$table = $db->getTableSchema('post');
```
El método retorna un objeto [[yii\db\TableSchema]] que contiene la información sobre las columnas de las tablas,
claves primarias, claves ajenas, etc. Toda esta información principalmente es utilizada por el
[constructor de consultas](db-query-builder.md) y [active record](db-active-record.md) para ayudar a
escribir código database-agnostic.
---
### Guide Es Db Migrations (`docs/guide-es/db-migrations.md`)
Migración de Base de Datos
==========================
Durante el curso de desarrollo y mantenimiento de una aplicación con base de datos, la estructura de dicha base de datos
evoluciona tanto como el código fuente. Por ejemplo, durante el desarrollo de una aplicación,
una nueva tabla podría ser necesaria; una vez que la aplicación se encuentra en producción, podría descrubrirse
que debería crearse un índice para mejorar el tiempo de ejecución de una consulta; y así sucesivamente. Debido a los cambios en la estructura de la base de datos
a menudo se requieren cambios en el código, Yii soporta la característica llamada *migración de base de datos*, la cual permite
tener un seguimiento de esos cambios en término de *migración de base de datos*, cuyo versionado es controlado
junto al del código fuente.
Los siguientes pasos muestran cómo una migración puede ser utilizada por un equipo durante el desarrollo:
1. Tim crea una nueva migración (por ej. crea una nueva table, cambia la definición de una columna, etc.).
2. Tim hace un commit con la nueva migración al sistema de control de versiones (por ej. Git, Mercurial).
3. Doug actualiza su repositorio desde el sistema de control de versiones y recibe la nueva migración.
4. Doug aplica dicha migración a su base de datos local de desarrollo, de ese modo sincronizando su base de datos
y reflejando los cambios que hizo Tim.
Los siguientes pasos muestran cómo hacer una puesta en producción con una migración de base de datos:
1. Scott crea un tag de lanzamiento en el repositorio del proyecto que contiene algunas migraciones de base de datos.
2. Scott actualiza el código fuente en el servidor de producción con el tag de lanzamiento.
3. Scott aplica cualquier migración de base de datos acumulada a la base de datos de producción.
Yii provee un grupo de herramientas de línea de comandos que te permite:
* crear nuevas migraciones;
* aplicar migraciones;
* revertir migraciones;
* re-aplicar migraciones;
* mostrar el historial y estado de migraciones.
Todas esas herramientas son accesibles a través del comando `yii migrate`. En esta sección describiremos en detalle
cómo lograr varias tareas utilizando dichas herramientas. Puedes a su vez ver el uso de cada herramienta a través del comando
de ayuda `yii help migrate`.
> Tip: las migraciones pueden no sólo afectar un esquema de base de datos sino también ajustar datos existentes para que encajen en el nuevo esquema, crear herencia RBAC
o también limpiar el cache.
## Creando Migraciones
Para crear una nueva migración, ejecuta el siguiente comando:
```
yii migrate/create
```
El argumento requerido `name` da una pequeña descripción de la nueva migración. Por ejemplo, si
la migración se trata acerca de crear una nueva tabla llamada *news*, podrías utilizar el nombre `create_news_table`
y ejecutar el siguiente comando:
```
yii migrate/create create_news_table
```
> Note: Debido a que el argumento `name` será utilizado como parte del nombre de clase de la migración generada,
sólo debería contener letras, dígitos, y/o guines bajos.
El comando anterior un nuevo archivo de clase PHP llamado `m150101_185401_create_news_table.php`
en el directorio `@app/migrations`. El archivo contendrá el siguiente código, que principalmente declara
una clase de tipo migración `m150101_185401_create_news_table` con el siguiente esqueleto de código:
```php
_`, donde
* `` se refiere a la marca de tiempo UTC en la cual el comando de migración fue ejecutado.
* `` es el mismo valor del argumento `name` provisto al ejecutar el comando.
En la clase de la migración, se espera que tu escribas código en el método `up()`, que realiza los cambios en la base de datos.
Podrías también querer introducir código en el método `down()`, que debería revertir los cambios realizados por `up()`. El método `up()` es llamado
cuando actualizas la base de datos con esta migración, mientras que el método `down()` es llamado cuando reviertes dicha migración.
El siguiente código muestra cómo podrías implementar la clase de migración para crear la tabla `news`:
```php
createTable('news', [
'id' => Schema::TYPE_PK,
'title' => Schema::TYPE_STRING . ' NOT NULL',
'content' => Schema::TYPE_TEXT,
]);
}
public function down()
{
$this->dropTable('news');
}
}
```
> Info: No todas las migraciones son reversibles. Por ejemplo, si el método `up()` elimina un registro en una tabla, podrías
no ser capáz de recuperarla en el método `down()`. A veces, podrías ser simplemente demasiado perezoso para implementar
el método `down()`, debido a que no es muy común revertir migraciones de base de datos. En este caso, deberías devolver
`false` en el método `down()` para indicar que dicha migración no es reversible.
La clase de migración de base de datos [[yii\db\Migration]] expone una conexión a la base de datos mediante la propiedad [[yii\db\Migration::db|db]].
Puedes utilizar esto para manipular el esquema de la base de datos utilizando métodos como se describen en
[Trabajando con Esquemas de Base de Datos](db-dao.md#database-schema).
En vez de utilizar tipos físicos, al crear tablas o columnas deberías utilizar los *tipos abstractos*
así las migraciones son independientes de algún DBMS específico. La clase [[yii\db\Schema]] define
un grupo de constantes que representan los tipos abstractos soportados. Dichas constantes son llamadas utilizando el formato
de `TYPE_`. Por ejemplo, `TYPE_PK` se refiere al tipo clave primaria auto-incremental; `TYPE_STRING`
se refiere al tipo string. Cuando se aplica una migración a una base de datos en particular, los tipos abstractos
serán traducidos a los tipos físicos correspondientes. En el caso de MySQL, `TYPE_PK` será transformado
en `int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY`, mientras `TYPE_STRING` se vuelve `varchar(255)`.
Puedes agregar restricciones adicionales al utilizar tipos abstractos. En el ejemplo anterior, ` NOT NULL` es agregado
a `Schema::TYPE_STRING` para especificar que la columna no puede ser `null`.
> Info: El mapeo entre tipos abstractos y tipos físicos es especificado en
la propiedad [[yii\db\QueryBuilder::$typeMap|$typeMap]] en cada clase concreta `QueryBuilder`.
Desde la versión 2.0.6, puedes hacer uso del recientemente introducido generador de esquemas, el cual provee una forma más conveniente de definir las columnas.
De esta manera, la migración anterior podría ser escrita así:
```php
createTable('news', [
'id' => $this->primaryKey(),
'title' => $this->string()->notNull(),
'content' => $this->text(),
]);
}
public function down()
{
$this->dropTable('news');
}
}
```
Existe una lista de todos los métodos disponibles para la definición de tipos de columna en la API de la documentación de [[yii\db\SchemaBuilderTrait]].
## Generar Migraciones
Desde la versión 2.0.7 la consola provee una manera muy conveniente de generar migraciones.
Si el nombre de la migración tiene una forma especial, por ejemplo `create_xxx_table` o `drop_xxx_table` entonces el archivo de la migración generada
contendrá código extra, en este caso para crear/eliminar tablas.
A continuación se describen todas estas variantes.
### Crear Tabla
```php
yii migrate/create create_post_table
```
esto genera
```php
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post_table extends Migration
{
/**
* {@inheritdoc}
*/
public function up()
{
$this->createTable('post', [
'id' => $this->primaryKey()
]);
}
/**
* {@inheritdoc}
*/
public function down()
{
$this->dropTable('post');
}
}
```
Para crear las columnas en ese momento, las puedes especificar vía la opción `--fields`.
```php
yii migrate/create create_post_table --fields="title:string,body:text"
```
genera
```php
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post_table extends Migration
{
/**
* {@inheritdoc}
*/
public function up()
{
$this->createTable('post', [
'id' => $this->primaryKey(),
'title' => $this->string(),
'body' => $this->text(),
]);
}
/**
* {@inheritdoc}
*/
public function down()
{
$this->dropTable('post');
}
}
```
Puedes especificar más parámetros para las columnas.
```php
yii migrate/create create_post_table --fields="title:string(12):notNull:unique,body:text"
```
genera
```php
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post_table extends Migration
{
/**
* {@inheritdoc}
*/
public function up()
{
$this->createTable('post', [
'id' => $this->primaryKey(),
'title' => $this->string(12)->notNull()->unique(),
'body' => $this->text()
]);
}
/**
* {@inheritdoc}
*/
public function down()
{
$this->dropTable('post');
}
}
```
> Note: la clave primaria es automáticamente agragada y llamada `id` por defecto. Si quieres utilizar otro nombre puedes
> especificarlo así `--fields="name:primaryKey"`.
#### Claves Foráneas
Desde 2.0.8 el generador soporta claves foráneas utilizando la palabra clave `foreignKey`.
```php
yii migrate/create create_post_table --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
```
genera
```
/* Detailed source-code truncated for AI context efficiency. */
```
La posición de la palabra clave `foreignKey` en la descripción de la columna
no cambia el código generado. Esto significa:
- `author_id:integer:notNull:foreignKey(user)`
- `author_id:integer:foreignKey(user):notNull`
- `author_id:foreignKey(user):integer:notNull`
Todas generan el mismo código.
La palabra clave `foreignKey` puede tomar un parámetro entre paréntesis el cual
será el nombre de la tabla relacionada por la clave foránea generada. Si no se pasa ningún parámetro
el nombre de la tabla será deducido en base al nombre de la columna.
En el ejemplo anterior `author_id:integer:notNull:foreignKey(user)` generará
una columna llamada `author_id` con una clave foránea a la tabla `user` mientras
`category_id:integer:defaultValue(1):foreignKey` generará
`category_id` con una clave foránea a la tabla `category`.
### Eliminar Tabla
```php
yii migrate/create drop_post_table --fields="title:string(12):notNull:unique,body:text"
```
genera
```php
class m150811_220037_drop_post_table extends Migration
{
public function up()
{
$this->dropTable('post');
}
public function down()
{
$this->createTable('post', [
'id' => $this->primaryKey(),
'title' => $this->string(12)->notNull()->unique(),
'body' => $this->text()
]);
}
}
```
### Agregar Columna
Si el nombre de la migración está en la forma `add_xxx_column_to_yyy_table` entonces el archivo generado contendrá
las declaraciones `addColumn` y `dropColumn` necesarias.
Para agregar una columna:
```php
yii migrate/create add_position_column_to_post_table --fields="position:integer"
```
genera
```php
class m150811_220037_add_position_column_to_post_table extends Migration
{
public function up()
{
$this->addColumn('post', 'position', $this->integer());
}
public function down()
{
$this->dropColumn('post', 'position');
}
}
```
### Eliminar Columna
Si el nombre de la migración está en la forma `drop_xxx_column_from_yyy_table` entonces el archivo generado contendrá
las declaraciones `addColumn` y `dropColumn` necesarias.
```php
yii migrate/create drop_position_column_from_post_table --fields="position:integer"
```
genera
```php
class m150811_220037_drop_position_column_from_post_table extends Migration
{
public function up()
{
$this->dropColumn('post', 'position');
}
public function down()
{
$this->addColumn('post', 'position', $this->integer());
}
}
```
### Agregar Tabla de Unión
Si el nombre de la migración está en la forma `create_junction_table_for_xxx_and_yyy_tables` entonces se generará el código necesario
para una tabla de unión.
```php
yii migrate/create create_junction_table_for_post_and_tag_tables --fields="created_at:dateTime"
```
genera
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Migraciones Transaccionales
Al ejecutar migraciones complejas de BD, es importante asegurarse que todas las migraciones funcionen o fallen como una unidad
así la base de datos puede mantener integridad y consistencia. Para alcanzar este objetivo, se recomienda que
encierres las operación de la BD de cada migración en una [transacción](db-dao.md#performing-transactions).
Una manera simple de implementar migraciones transaccionales es poniendo el código de las migraciones en los métodos `safeUp()` y `safeDown()`.
Estos métodos se diferencias con `up()` y `down()` en que son encerrados implícitamente en una transacción.
Como resultado, si alguna de las operaciones dentro de estos métodos falla, todas las operaciones previas son automáticamente revertidas.
En el siguiente ejemplo, además de crear la tabla `news` también insertamos un registro inicial dentro de la dicha tabla.
```php
createTable('news', [
'id' => $this->primaryKey(),
'title' => $this->string()->notNull(),
'content' => $this->text(),
]);
$this->insert('news', [
'title' => 'test 1',
'content' => 'content 1',
]);
}
public function safeDown()
{
$this->delete('news', ['id' => 1]);
$this->dropTable('news');
}
}
```
Ten en cuenta que usualmente cuando ejecutas múltiples operaciones en la BD en `safeUp()`, deberías revertir su orden de ejecución
en `safeDown()`. En el ejemplo anterior primero creamos la tabla y luego insertamos la finla en `safeUp()`; mientras
que en `safeDown()` primero eliminamos el registro y posteriormente eliminamos la tabla.
> Note: No todos los DBMS soportan transacciones. Y algunas consultas a la BD no pueden ser puestas en transacciones. Para algunos ejemplos,
por favor lee acerca de [commits implícitos](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html). En estos casos,
deberías igualmente implementar `up()` y `down()`.
### Métodos de Acceso a la Base de Datos
La clase base [[yii\db\Migration]] provee un grupo de métodos que te permiten acceder y manipular bases de datos.
Podrías encontrar que estos métodos son nombrados de forma similar a los [métodos DAO](db-dao.md) provistos por la clase [[yii\db\Command]].
Por ejemplo, el método [[yii\db\Migration::createTable()]] te permite crear una nueva tabla,
tal como lo hace [[yii\db\Command::createTable()]].
El beneficio de utilizar lo métodos provistos por [[yii\db\Migration]] es que no necesitas explícitamente
crear instancias de [[yii\db\Command]], y la ejecución de cada método mostrará automáticamente mensajes útiles
diciéndote qué operaciones de la base de datos se realizaron y cuánto tiempo tomaron.
Debajo hay una lista de todos los métodos de acceso a la base de datos:
* [[yii\db\Migration::execute()|execute()]]: ejecuta una declaración SQL
* [[yii\db\Migration::insert()|insert()]]: inserta un único registro
* [[yii\db\Migration::batchInsert()|batchInsert()]]: inserta múltiples registros
* [[yii\db\Migration::update()|update()]]: actualiza registros
* [[yii\db\Migration::delete()|delete()]]: elimina registros
* [[yii\db\Migration::createTable()|createTable()]]: crea una nueva tabla
* [[yii\db\Migration::renameTable()|renameTable()]]: renombra una tabla
* [[yii\db\Migration::dropTable()|dropTable()]]: elimina una tabla
* [[yii\db\Migration::truncateTable()|truncateTable()]]: elimina todos los registros de una tabla
* [[yii\db\Migration::addColumn()|addColumn()]]: agrega una columna
* [[yii\db\Migration::renameColumn()|renameColumn()]]: renombra una columna
* [[yii\db\Migration::dropColumn()|dropColumn()]]: elimina una columna
* [[yii\db\Migration::alterColumn()|alterColumn()]]: modifica una columna
* [[yii\db\Migration::addPrimaryKey()|addPrimaryKey()]]: agrega una clave primaria
* [[yii\db\Migration::dropPrimaryKey()|dropPrimaryKey()]]: elimina una clave primaria
* [[yii\db\Migration::addForeignKey()|addForeignKey()]]: agrega una clave foránea
* [[yii\db\Migration::dropForeignKey()|dropForeignKey()]]: elimina una clave foránea
* [[yii\db\Migration::createIndex()|createIndex()]]: crea un índice
* [[yii\db\Migration::dropIndex()|dropIndex()]]: elimina un índice
* [[yii\db\Migration::addCommentOnColumn()|addCommentOnColumn()]]: agrega un comentario a una columna
* [[yii\db\Migration::dropCommentFromColumn()|dropCommentFromColumn()]]: elimina un comentario de una columna
* [[yii\db\Migration::addCommentOnTable()|addCommentOnTable()]]: agrega un comentario a una tabla
* [[yii\db\Migration::dropCommentFromTable()|dropCommentFromTable()]]: elimina un comentario de una tabla
> Info: [[yii\db\Migration]] no provee un método de consulta a la base de datos. Esto es porque normalmente no necesitas
mostrar mensajes detallados al traer datos de una base de datos. También se debe a que puedes utilizar el poderoso
[Query Builder](db-query-builder.md) para generar y ejecutar consultas complejas.
> Note: Al manipular datos utilizando una migración podrías encontrar que utilizando tus clases [Active Record](db-active-record.md)
> para esto podría ser útil ya que algo de la lógica ya está implementada ahí. Ten en cuenta de todos modos, que en contraste con
> el código escrito en las migraciones, cuya naturaleza es permanecer constante por siempre, la lógica de la aplicación está sujeta a cambios.
> Entonces al utilizar Active Record en migraciones, los cambios en la lógica en la capa Active Record podrían accidentalmente romper
> migraciones existentes. Por esta razón, el código de las migraciones debería permanecer independiente de determinada lógica de la aplicación
> tal como clases Active Record.
## Aplicar Migraciones
To upgrade a database to its latest structure, you should apply all available new migrations using the following command:
Para actualizar una base de datos a su última estructura, deberías aplicar todas las nuevas migraciones utilizando el siguiente comando:
```
yii migrate
```
Este comando listará todas las migraciones que no han sido aplicadas hasta el momento. Si confirmas que quieres aplicar
dichas migraciones, se correrá el método `up()` o `safeUp()` en cada clase de migración nueva, una tras otra,
en el orden de su valor de marca temporal. Si alguna de las migraciones falla, el comando terminará su ejecución sin aplicar
el resto de las migraciones.
> Tip: En caso de no disponer de la línea de comandos en el servidor, podrías intentar utilizar
> la extensión [web shell](https://github.com/samdark/yii2-webshell).
Por cada migración aplicada correctamente, el comando insertará un registro en la base de datos, en la tabla llamada
`migration` para registrar la correcta aplicación de la migración. Esto permitirá a la herramienta de migración identificar
cuáles migraciones han sido aplicadas y cuáles no.
> Info: La herramienta de migración creará automáticamente la tabla `migration` en la base de datos especificada
en la opción [[yii\console\controllers\MigrateController::db|db]] del comando. Por defecto, la base de datos
es especificada en el [componente de aplicación](structure-application-components.md) `db`.
A veces, podrías sólo querer aplicar una o algunas pocas migraciones, en vez de todas las migraciones disponibles.
Puedes hacer esto el número de migraciones que quieres aplicar al ejecutar el comando.
Por ejemplo, el siguiente comando intentará aplicar las tres siguientes migraciones disponibles:
```
yii migrate 3
```
Puedes además explícitamente especificar una migración en particular a la cual la base de datos debería migrar
utilizando el comando `migrate/to` de acuerdo a uno de los siguientes formatos:
```
yii migrate/to 150101_185401 # utiliza la marca temporal para especificar la migración
yii migrate/to "2015-01-01 18:54:01" # utiliza un string que puede ser analizado por strtotime()
yii migrate/to m150101_185401_create_news_table # utiliza el nombre completo
yii migrate/to 1392853618 # utiliza el tiempo UNIX
```
Si hubiera migraciones previas a la especificada sin aplicar, estas serán aplicadas antes de que la migración especificada
sea aplicada.
Si la migración especificada ha sido aplicada previamente, cualquier migración aplicada posteriormente será revertida.
## Revertir Migraciones
Para revertir (deshacer) una o varias migraciones ya aplicadas, puedes ejecutar el siguiente comando:
```
yii migrate/down # revierte la más reciente migración aplicada
yii migrate/down 3 # revierte las 3 últimas migraciones aplicadas
```
> Note: No todas las migraciones son reversibles. Intentar revertir tales migraciones producirá un error y detendrá
completamente el proceso de reversión.
## Rehacer Migraciones
Rehacer (re-ejecutar) migraciones significa primero revertir las migraciones especificadas y luego aplicarlas nuevamente. Esto puede hacerse
de esta manera:
```
yii migrate/redo # rehace la más reciente migración aplicada
yii migrate/redo 3 # rehace las 3 últimas migraciones aplicadas
```
> Note: Si una migración no es reversible, no tendrás posibilidades de rehacerla.
## Listar Migraciones
Para listar cuáles migraciones han sido aplicadas y cuáles no, puedes utilizar los siguientes comandos:
```
yii migrate/history # muestra las últimas 10 migraciones aplicadas
yii migrate/history 5 # muestra las últimas 5 migraciones aplicadas
yii migrate/history all # muestra todas las migraciones aplicadas
yii migrate/new # muestra las primeras 10 nuevas migraciones
yii migrate/new 5 # muestra las primeras 5 nuevas migraciones
yii migrate/new all # muestra todas las nuevas migraciones
```
## Modificar el Historial de Migraciones
En vez de aplicar o revertir migraciones, a veces simplemente quieres marcar que tu base de datos
ha sido actualizada a una migración en particular. Esto sucede normalmente cuando cambias manualmente la base de datos
a un estado particular y no quieres que la/s migración/es de ese cambio sean re-aplicadas posteriormente. Puedes alcanzar este objetivo
con el siguiente comando:
```
yii migrate/mark 150101_185401 # utiliza la marca temporal para especificar la migración
yii migrate/mark "2015-01-01 18:54:01" # utiliza un string que puede ser analizado por strtotime()
yii migrate/mark m150101_185401_create_news_table # utiliza el nombre completo
yii migrate/mark 1392853618 # utiliza el tiempo UNIX
```
El comando modificará la tabla `migration` agregando o eliminado ciertos registros para indicar que en la base de datos
han sido aplicadas las migraciones hasta la especificada. Ninguna migración será aplicada ni revertida por este comando.
## Personalizar Migraciones
Hay varias maneras de personalizar el comando de migración.
### Utilizar Opciones de la Línea de Comandos
El comando de migración trae algunas opciones de línea de comandos que pueden ser utilizadas para personalizar su comportamiento:
* `interactive`: boolean (por defecto `true`), especificar si se debe ejecutar la migración en modo interactivo.
Cuando se indica `true`, se le pedirá confirmación al usuario antes de ejecutar ciertas acciones.
Puedes querer definirlo como `false` si el comando está siendo utilizado como un proceso de fondo.
* `migrationPath`: string (por defecto `@app/migrations`), especifica el directorio que contiene todos los archivos
de clase de las migraciones. Este puede ser especificado tanto como una ruta a un directorio un [alias](concept-aliases.md) de ruta.
Ten en cuenta que el directorio debe existir, o el comando disparará un error.
* `migrationTable`: string (por defecto `migration`), especifica el nombre de la tabla de la base de datos que almacena
información del historial de migraciones. Dicha tabla será creada por el comando en caso de que no exista.
Puedes también crearla manualmente utilizando la estructura `version varchar(255) primary key, apply_time integer`.
* `db`: string (por defecto `db`), especifica el ID del [componente de aplicación](structure-application-components.md) de la base de datos.
Esto representa la base de datos que será migrada en este comando.
* `templateFile`: string (por defecto `@yii/views/migration.php`), especifica la ruta al template
utilizado para generar el esqueleto de los archivos de clases de migración. Puede ser especificado tanto como una ruta a un archivo
como una [alias](concept-aliases.md) de una ruta. El template es un archivo PHP en el cual puedes utilizar una variable predefinida
llamada `$className` para obtener el nombre de clase de la migración.
* `generatorTemplateFiles`: array (por defecto `[
'create_table' => '@yii/views/createTableMigration.php',
'drop_table' => '@yii/views/dropTableMigration.php',
'add_column' => '@yii/views/addColumnMigration.php',
'drop_column' => '@yii/views/dropColumnMigration.php',
'create_junction' => '@yii/views/createTableMigration.php'
]`), especifica los templates utilizados para generar las migraciones. Ver "[Generar Migraciones](#generating-migrations)"
para más detalles.
* `fields`: array de strings de definiciones de columna utilizado por el código de migración. Por defecto `[]`. El formato de cada
definición es `COLUMN_NAME:COLUMN_TYPE:COLUMN_DECORATOR`. Por ejemplo, `--fields=name:string(12):notNull` produce
una columna string de tamaño 12 que es not `null`.
El siguiente ejemplo muestra cómo se pueden utilizar estas opciones.
Por ejemplo, si queremos migrar un módulo `forum` cuyos arhivos de migración
están ubicados dentro del directorio `migrations` del módulo, podemos utilizar el siguientedocs/guide-es/db-migrations.md
comando:
```
# realiza las migraciones de un módulo forum sin interacción del usuario
yii migrate --migrationPath=@app/modules/forum/migrations --interactive=0
```
### Configurar el Comando Globalmente
En vez de introducir los valores de las opciones cada vez que ejecutas un comandod e migración, podrías configurarlos
de una vez por todas en la configuración de la aplicación como se muestra a continuación:
```php
return [
'controllerMap' => [
'migrate' => [
'class' => 'yii\console\controllers\MigrateController',
'migrationTable' => 'backend_migration',
],
],
];
```
Con esta configuración, cada vez que ejecutes un comando de migración, la tabla `backend_migration`
será utilizada para registrar el historial de migraciones. No necesitarás volver a especificarla con la opción `migrationTable`
de la línea de comandos.
## Migrar Múltiples Bases de Datos
Por defecto, las migraciones son aplicadas en la misma base de datos especificada en el [componente de aplicación](structure-application-components.md) `db`.
Si quieres que sean aplicadas en una base de datos diferente, puedes especificar la opción `db` como se muestra a continuación,
```
yii migrate --db=db2
```
El comando anterior aplicará las migraciones en la base de datos `db2`.
A veces puede suceder que quieras aplicar *algunas* de las migraciones a una base de datos, mientras algunas otras
a una base de datos distinta. Para lograr esto, al implementar una clase de migración debes especificar explícitamente el ID del componente DB
que la migración debe utilizar, como a continuación:
```php
db = 'db2';
parent::init();
}
}
```
La migración anterior se aplicará a `db2`, incluso si especificas una base de datos diferente en la opción `db` de la
línea de comandos. Ten en cuenta que el historial aún será registrado in la base de datos especificada en la opción `db` de la línea de comandos.
Si tienes múltiples migraciones que utilizan la misma base de datos, es recomandable que crees una clase base de migración
con el código `init()` mostrado. Entonces cada clase de migración puede extender de esa clase base.
> Tip: Aparte de definir la propiedad [[yii\db\Migration::db|db]], puedes también operar en diferentes bases de datos
creando nuevas conexiones de base de datos en tus clases de migración. También puedes utilizar [métodos DAO](db-dao.md)
con esas conexiones para manipular diferentes bases de datos.
Another strategy that you can take to migrate multiple databases is to keep migrations for different databases in
different migration paths. Then you can migrate these databases in separate commands like the following:
Otra estrategia que puedes seguir para migrar múltiples bases de datos es mantener las migraciones para diferentes bases de datos en
distintas rutas de migración. Entonces podrías migrar esas bases de datos en comandos separados como a continuación:
```
yii migrate --migrationPath=@app/migrations/db1 --db=db1
yii migrate --migrationPath=@app/migrations/db2 --db=db2
...
```
El primer comando aplicará las migraciones que se encuentran en `@app/migrations/db1` en la base de datos `db1`, el segundo comando
aplicará las migraciones que se encuentran en `@app/migrations/db2` en `db2`, y así sucesivamente.
---
### Guide Es Db Query Builder (`docs/guide-es/db-query-builder.md`)
Constructor de Consultas
========================
> Note: Esta sección está en desarrollo.
Yii proporciona una capa de acceso básico a bases de datos como se describe en la sección
[Objetos de Acceso a Bases de Datos](db-dao.md). La capa de acceso a bases de datos proporciona un método de bajo
nivel (low-level) para interaccionar con la base de datos. Aunque a veces puede ser útil la escritura de sentencias
SQLs puras, en otras situaciones puede ser pesado y propenso a errores. Otra manera de tratar con bases de datos puede
ser el uso de Constructores de Consultas (Query Builder). El Constructor de Consultas proporciona un medio orientado a
objetos para generar las consultas que se ejecutarán.
Un uso típico de Constructor de Consultas puede ser el siguiente:
```php
$rows = (new \yii\db\Query())
->select('id, name')
->from('user')
->limit(10)
->all();
// que es equivalente al siguiente código:
$query = (new \yii\db\Query())
->select('id, name')
->from('user')
->limit(10);
// Crear un comando. Se puede obtener la consulta SQL actual utilizando $command->sql
$command = $query->createCommand();
// Ejecutar el comando:
$rows = $command->queryAll();
```
Métodos de Consulta
-------------------
Como se puede observar, primero se debe tratar con [[yii\db\Query]]. En realidad, `Query` sólo se encarga de
representar diversa información de la consulta. La lógica para generar la consulta se efectúa mediante
[[yii\db\QueryBuilder]] cuando se llama al método `createCommand()`, y la ejecución de la consulta la efectúa
[[yii\db\Command]].
Se ha establecido, por convenio, que [[yii\db\Query]] proporcione un conjunto de métodos de consulta comunes que
construirán la consulta, la ejecutarán, y devolverán el resultado. Por ejemplo:
- [[yii\db\Query::all()|all()]]: construye la consulta, la ejecuta y devuelve todos los resultados en formato de array.
- [[yii\db\Query::one()|one()]]: devuelve la primera fila del resultado.
- [[yii\db\Query::column()|column()]]: devuelve la primera columna del resultado.
- [[yii\db\Query::scalar()|scalar()]]: devuelve la primera columna en la primera fila del resultado.
- [[yii\db\Query::exists()|exists()]]: devuelve un valor indicando si la el resultado devuelve algo.
- [[yii\db\Query::count()|count()]]: devuelve el resultado de la consulta `COUNT`. Otros métodos similares incluidos
son `sum($q)`, `average($q)`, `max($q)`, `min($q)`, que soportan las llamadas funciones de agregación. El parámetro
`$q` es obligatorio en estos métodos y puede ser el nombre de la columna o expresión.
Construcción de Consultas
-------------------------
A continuación se explicará como construir una sentencia SQL que incluya varias clausulas. Para simplificarlo, usamos
`$query` para representar el objeto [[yii\db\Query]]:
### `SELECT`
Para formar una consulta `SELECT` básica, se necesita especificar que columnas y de que tablas se seleccionarán:
```php
$query->select('id, name')
->from('user');
```
Las opciones de select se pueden especificar como una cadena de texto (string) separada por comas o como un array. La
sintaxis del array es especialmente útil cuando se forma la selección dinámicamente.
```php
$query->select(['id', 'name'])
->from('user');
```
> Info: Se debe usar siempre el formato array si la clausula `SELECT` contiene expresiones SQL. Esto se debe a
que una expresión SQL como `CONCAT(first_name, last_name) AS full_name` puede contener comas. Si se junta con otra
cadena de texto de otra columna, puede ser que la expresión se divida en varias partes por comas, esto puede
conllevar a errores.
Cuando se especifican columnas, se pueden incluir los prefijos de las tablas o alias de columnas, ej. `user.id`,
`user.id AS user_id`. Si se usa un array para especificar las columnas, también se pueden usar las claves del array
para especificar los alias de columna, ej. `['user_id' => 'user.id', 'user_name' => 'user.name']`.
A partir de la versión 2.0.1, también se pueden seleccionar subconsultas como columnas. Por ejemplo:
```php
$subQuery = (new Query)->select('COUNT(*)')->from('user');
$query = (new Query)->select(['id', 'count' => $subQuery])->from('post');
// $query representa la siguiente sentencia SQL:
// SELECT `id`, (SELECT COUNT(*) FROM `user`) AS `count` FROM `post`
```
Para seleccionar filas distintas, se puede llamar a `distinct()`, como se muestra a continuación:
```php
$query->select('user_id')->distinct()->from('post');
```
### `FROM`
Para especificar de que tabla(s) se quieren seleccionar los datos, se llama a `from()`:
```php
$query->select('*')->from('user');
```
Se pueden especificar múltiples tablas usando una cadena de texto separado por comas o un array. Los nombres de tablas
pueden contener prefijos de esquema (ej. `'public.user'`) y/o alias de tablas (ej. `'user u'). El método
entrecomillara automáticamente los nombres de tablas a menos que contengan algún paréntesis (que significa que se
proporciona la tabla como una subconsulta o una expresión de BD). Por ejemplo:
```php
$query->select('u.*, p.*')->from(['user u', 'post p']);
```
Cuando se especifican las tablas como un array, también se pueden usar las claves de los arrays como alias de tablas
(si una tabla no necesita alias, no se usa una clave en formato texto). Por ejemplo:
```php
$query->select('u.*, p.*')->from(['u' => 'user', 'p' => 'post']);
```
Se puede especificar una subconsulta usando un objeto `Query`. En este caso, la clave del array correspondiente se
usará como alias para la subconsulta.
```php
$subQuery = (new Query())->select('id')->from('user')->where('status=1');
$query->select('*')->from(['u' => $subQuery]);
```
### `WHERE`
Habitualmente se seleccionan los datos basándose en ciertos criterios. El Constructor de Consultas tiene algunos
métodos útiles para especificarlos, el más poderoso de estos es `where`, y se puede usar de múltiples formas.
La manera más simple para aplicar una condición es usar una cadena de texto:
```php
$query->where('status=:status', [':status' => $status]);
```
Cuando se usan cadenas de texto, hay que asegurarse que se unen los parámetros de la consulta, no crear una consulta
mediante concatenación de cadenas de texto. El enfoque anterior es seguro, el que se muestra a continuación, no lo es:
```php
$query->where("status=$status"); // Peligroso!
```
En lugar de enlazar los valores de estado inmediatamente, se puede hacer usando `params` o `addParams`:
```php
$query->where('status=:status');
$query->addParams([':status' => $status]);
```
Se pueden establecer múltiples condiciones en `where` usando el *formato hash*.
```php
$query->where([
'status' => 10,
'type' => 2,
'id' => [4, 8, 15, 16, 23, 42],
]);
```
El código generará la el siguiente SQL:
```sql
WHERE (`status` = 10) AND (`type` = 2) AND (`id` IN (4, 8, 15, 16, 23, 42))
```
El valor NULO es un valor especial en las bases de datos, y el Constructor de Consultas lo gestiona inteligentemente.
Este código:
```php
$query->where(['status' => null]);
```
da como resultado la siguiente cláusula WHERE:
```sql
WHERE (`status` IS NULL)
```
También se pueden crear subconsultas con objetos de tipo `Query` como en el siguiente ejemplo:
```php
$userQuery = (new Query)->select('id')->from('user');
$query->where(['id' => $userQuery]);
```
que generará el siguiente código SQL:
```sql
WHERE `id` IN (SELECT `id` FROM `user`)
```
Otra manera de usar el método es el formato de operando que es `[operator, operand1, operand2, ...]`.
El operando puede ser uno de los siguientes (ver también [[yii\db\QueryInterface::where()]]):
- `and`: los operandos deben concatenerase usando `AND`. por ejemplo, `['and', 'id=1', 'id=2']` generará
`id=1 AND id=2`. Si el operando es un array, se convertirá en una cadena de texto usando las reglas aquí descritas.
Por ejemplo, `['and', 'type=1', ['or', 'id=1', 'id=2']]` generará `type=1 AND (id=1 OR id=2)`. El método no
ejecutará ningún filtrado ni entrecomillado.
- `or`: similar al operando `and` exceptuando que los operando son concatenados usando `OR`.
- `between`: el operando 1 debe ser el nombre de columna, y los operandos 2 y 3 deben ser los valores iniciales y
finales del rango en el que se encuentra la columna. Por ejemplo, `['between', 'id', 1, 10]` generará
`id BETWEEN 1 AND 10`.
- `not between`: similar a `between` exceptuando que `BETWEEN` se reemplaza por `NOT BETWEEN` en la condición
generada.
- `in`: el operando 1 debe ser una columna o una expresión de BD. El operando 2 puede ser un array o un objeto de tipo
`Query`. Generará una condición `IN`. Si el operando 2 es un array, representará el rango de valores que puede
albergar la columna o la expresión de BD; Si el operando 2 es un objeto de tipo `Query`, se generará una subconsulta
y se usará como rango de la columna o de la expresión de BD. Por ejemplo, `['in', 'id', [1, 2, 3]]` generará
`id IN (1, 2, 3)`. El método entrecomillará adecuadamente el nombre de columna y filtrará los valores del rango. El
operando `in` también soporta columnas compuestas. En este caso, el operando 1 debe se un array de columnas,
mientras que el operando 2 debe ser un array de arrays o un objeto de tipo `Query` que represente el rango de las
columnas.
- `not in`: similar que el operando `in` exceptuando que `IN` se reemplaza por `NOT IN` en la condición generada.
- `like`: el operando 1 debe ser una columna o una expresión de BD, y el operando 2 debe ser una cadena de texto o un
array que represente los valores a los que tienen que asemejarse la columna o la expresión de BD.Por ejemplo,
`['like', 'name', 'tester']` generará `name LIKE '%tester%'`. Cuando se da el valor rango como un array, se
generarán múltiples predicados `LIKE` y se concatenaran usando `AND`. Por ejemplo,
`['like', 'name', ['test', 'sample']]` generará `name LIKE '%test%' AND name LIKE '%sample%'`. También se puede
proporcionar un tercer operando opcional para especificar como deben filtrarse los caracteres especiales en los
valores. El operando debe se un array que mapeen los caracteres especiales a sus caracteres filtrados asociados. Si
no se proporciona este operando, se aplicará el mapeo de filtrado predeterminado. Se puede usar `false` o un array
vacío para indicar que los valores ya están filtrados y no se necesita aplicar ningún filtro. Hay que tener en
cuenta que cuando se usa un el mapeo de filtrado (o no se especifica el tercer operando), los valores se encerraran
automáticamente entre un par de caracteres de porcentaje.
> Note: Cuando se usa PostgreSQL también se puede usar
[`ilike`](https://www.postgresql.org/docs/8.3/static/functions-matching.html#FUNCTIONS-LIKE) en lugar de `like` para
filtrar resultados insensibles a mayúsculas (case-insensitive).
- `or like`: similar al operando `like` exceptuando que se usa `OR` para concatenar los predicados `LIKE` cuando haya
un segundo operando en un array.
- `not like`: similar al operando `like` exceptuando que se usa `LIKE` en lugar de `NOT LIKE` en las condiciones
generadas.
- `or not like`: similar al operando `not like` exceptuando que se usa `OR` para concatenar los predicados `NOT LIKE`.
- `exists`: requiere un operando que debe ser una instancia de [[yii\db\Query]] que represente la subconsulta. Esto
generará una expresión `EXISTS (sub-query)`.
- `not exists`: similar al operando `exists` y genera una expresión `NOT EXISTS (sub-query)`.
Adicionalmente se puede especificar cualquier cosa como operando:
```php
$query->select('id')
->from('user')
->where(['>=', 'id', 10]);
```
Cuyo resultado será:
```sql
SELECT id FROM user WHERE id >= 10;
```
Si se construyen partes de una condición dinámicamente, es muy convenientes usar `andWhere()` y `orWhere()`:
```php
$status = 10;
$search = 'yii';
$query->where(['status' => $status]);
if (!empty($search)) {
$query->andWhere(['like', 'title', $search]);
}
```
En el caso que `$search` no este vacío, se generará el siguiente código SQL:
```sql
WHERE (`status` = 10) AND (`title` LIKE '%yii%')
```
#### Construcción de Condiciones de Filtro
Cuando se generan condiciones de filtro basadas en datos recibidos de usuarios (inputs), a menudo se quieren gestionar
de forma especial las "datos vacíos" para ignorarlos en los filtros. Por ejemplo, teniendo un formulario HTML que
obtiene el nombre de usuario y la dirección de correo electrónico. Si el usuario solo rellena el campo de nombre de
usuario, se puede querer generar una consulta para saber si el nombre de usuario recibido es valido. Se puede usar
`filterWhere()` para conseguirlo:
```php
// $username y $email son campos de formulario rellenados por usuarios
$query->filterWhere([
'username' => $username,
'email' => $email,
]);
```
El método `filterWhere()` es muy similar al método `where()`. La principal diferencia es que el `filterWhere()`
eliminará los valores vacíos de las condiciones proporcionadas. Por lo tanto si `$email` es "vació", la consulta
resultante será `...WHERE username=:username`; y si tanto `$username` como `$email` son "vacías", la consulta no
tendrá `WHERE`.
Decimos que un valor es *vacío* si es nulo, una cadena de texto vacía, una cadena de texto que consista en espacios en
blanco o un array vacío.
También se pueden usar `andFilterWhere()` y `orFilterWhere()` para añadir más condiciones de filtro.
### `ORDER BY`
Se pueden usar `orderBy` y `addOrderBy` para ordenar resultados:
```php
$query->orderBy([
'id' => SORT_ASC,
'name' => SORT_DESC,
]);
```
Aquí estamos ordenando por `id` ascendente y después por `name` descendente.
### `GROUP BY` and `HAVING`
Para añadir `GROUP BY` al SQL generado se puede usar el siguiente código:
```php
$query->groupBy('id, status');
```
Si se quieren añadir otro campo después de usar `groupBy`:
```php
$query->addGroupBy(['created_at', 'updated_at']);
```
Para añadir la condición `HAVING` se pueden usar los métodos `having` y `andHaving` y `orHaving`. Los parámetros para
ellos son similares a los del grupo de métodos `where`:
```php
$query->having(['status' => $status]);
```
### `LIMIT` and `OFFSET`
Para limitar el resultado a 10 filas se puede usar `limit`:
```php
$query->limit(10);
```
Para saltarse las 100 primeras filas, se puede usar:
```php
$query->offset(100);
```
### `JOIN`
Las clausulas `JOIN` se generan en el Constructor de Consultas usando el método join aplicable:
- `innerJoin()`
- `leftJoin()`
- `rightJoin()`
Este left join selecciona los datos desde dos tablas relacionadas en una consulta:
```php
$query->select(['user.name AS author', 'post.title as title'])
->from('user')
->leftJoin('post', 'post.user_id = user.id');
```
En el código, el primer parámetro del método `leftjoin` especifica la tabla a la que aplicar el join. El segundo
parámetro, define la condición del join.
Si la aplicación de bases de datos soporta otros tipos de joins, se pueden usar mediante el método `join` genérico:
```php
$query->join('FULL OUTER JOIN', 'post', 'post.user_id = user.id');
```
El primer argumento es el tipo de join a realizar. El segundo es la tabla a la que aplicar el join, y el tercero es la condición:
Como en `FROM`, también se pueden efectuar joins con subconsultas. Para hacerlo, se debe especificar la subconsulta
como un array que tiene que contener un elemento. El valor del array tiene que ser un objeto de tipo `Query` que
represente la subconsulta, mientras que la clave del array es el alias de la subconsulta. Por ejemplo:
```php
$query->leftJoin(['u' => $subQuery], 'u.id=author_id');
```
### `UNION`
En SQL `UNION` agrega resultados de una consulta a otra consulta. Las columnas devueltas por ambas consultas deben
coincidir. En Yii para construirla, primero se pueden formar dos objetos de tipo query y después usar el método
`union`:
```php
$query = new Query();
$query->select("id, category_id as type, name")->from('post')->limit(10);
$anotherQuery = new Query();
$anotherQuery->select('id, type, name')->from('user')->limit(10);
$query->union($anotherQuery);
```
Consulta por Lotes
---------------
Cuando se trabaja con grandes cantidades de datos, los métodos como [[yii\db\Query::all()]] no son adecuados ya que
requieren la carga de todos los datos en memoria. Para mantener los requerimientos de memoria reducidos, Yii
proporciona soporte a las llamadas consultas por lotes (batch query). Una consulta por lotes usa un cursor de datos y
recupera los datos en bloques.
Las consultas por lotes se pueden usar del siguiente modo:
```php
use yii\db\Query;
$query = (new Query())
->from('user')
->orderBy('id');
foreach ($query->batch() as $users) {
// $users is an array of 100 or fewer rows from the user table
}
// o si se quieren iterar las filas una a una
foreach ($query->each() as $user) {
// $user representa uno fila de datos de la tabla user
}
```
Los métodos [[yii\db\Query::batch()]] y [[yii\db\Query::each()]] devuelven un objeto [[yii\db\BatchQueryResult]] que
implementa una interfaz `Iterator` y así se puede usar en el constructor `foreach`. Durante la primera iteración, se
efectúa una consulta SQL a la base de datos. Desde entonces, los datos se recuperan por lotes en las iteraciones. El
tamaño predeterminado de los lotes es 100, que significa que se recuperan 100 filas de datos en cada lote. Se puede
modificar el tamaño de los lotes pasando pasando un primer parámetro a los métodos `batch()` o `each()`.
En comparación con [[yii\db\Query::all()]], las consultas por lotes sólo cargan 100 filas de datos en memoria cada
vez. Si el procesan los datos y después se descartan inmediatamente, las consultas por lotes, pueden ayudar a mantener
el uso de memora bajo un limite.
Si se especifica que el resultado de la consulta tiene que ser indexado por alguna columna mediante
[[yii\db\Query::indexBy()]], las consultas por lotes seguirán manteniendo el indice adecuado. Por ejemplo,
```php
use yii\db\Query;
$query = (new Query())
->from('user')
->indexBy('username');
foreach ($query->batch() as $users) {
// $users esta indexado en la columna "username"
}
foreach ($query->each() as $username => $user) {
}
```
---
### Guide Es Glossary (`docs/guide-es/glossary.md`)
# A
## alias
Alias es un string utilizado por Yii para referirse a una clase o directorio tal como `@app/vendor`.
## aplicación
La aplicación es el objeto central durante la solicitud HTTP. Contiene un número de componentes con los que toma información de la solicitud y la envía al controlador apropiado para posterior procesamiento.
El objeto de la aplicación es instanciado como un singleton por el script de entrada. El singleton de la aplicación puede ser accedido desde cualquier lugar a través de `\Yii::$app`.
## assets
Asset se refiere a un archivo de recurso. Típicamente contiene JavaScript o CSS pero puede ser cualquier otra cosa que sea accesible vía HTTP.
## atributo
Un atributo es una propiedad de un modelo (una variable miembro de clase o una propiedad mágica definida vía `__get()`/`__set()`) que almacena **datos de negocio**.
# B
## bundle
Bundle, conocido como paquete en Yii 1.1, se refiere a un número de recursos y un archivo de configuración que describe dependencias y lista recursos.
# C
## configuración
Configuración puede referirse tanto al proceso de establecer propiedades de un objeto como a un archivo de configuración que almacena la definición de propiedades para un objeto o clase de objetos.
# E
## extensión
Extensión es un grupo de clases, paquete de recursos y configuraciones que agrega más características a la aplicación.
# I
## instalación
Instalación es el proceso de preparar algo para trabajar, desde seguir un archivo léame hasta ejecutar un script preparado especialmente para tal fin. En el caso de Yii, define permisos y chequea los requerimientos para el funcionamiento del software.
# M
## módulo
Módulo es una sub-aplicación que contiene elementos MVC en sí mismo, como modelos, vistas, controladores, etc. y puede ser utilizado dentro de la aplicación principal. Típicamente remitiendo las solicitudes al módulo en vez de manejándolo desde controladores.
# N
## namespace
Namespace (espacio de nombres) se refiere a una [característica de PHP](https://www.php.net/manual/es/language.namespaces.php) activamente utilizada en Yii 2.
# P
## paquete
[Ver bundle](#bundle).
# V
## vendor
Vendor (proveedor) es una organización o un desarrollador individual que provee código en forma de extensiones, módulos o librerías.
---
### Guide Es Helper Array (`docs/guide-es/helper-array.md`)
ArrayHelper
===========
Adicionalmente al [rico conjunto de funciones para arrays de PHP](https://www.php.net/manual/es/book.array.php), el array helper de Yii proporciona
métodos estáticos adicionales permitiendo trabajar con arrays de manera más eficiente.
## Devolviendo Valores
Recuperar valores de un array, un objeto o una estructura compleja usando PHP estándar es bastante
repetitivo. Tienes que comprobar primero si una clave existe con `isset`, después devolver el valor si existe, si no,
devolver un valor por defecto:
```php
class User
{
public $name = 'Alex';
}
$array = [
'foo' => [
'bar' => new User(),
]
];
$value = isset($array['foo']['bar']->name) ? $array['foo']['bar']->name : null;
```
Yii proviene de un método muy conveniente para hacerlo:
```php
$value = ArrayHelper::getValue($array, 'foo.bar.name');
```
El primer argumento del método es de donde vamos a obtener el valor. El segundo argumento especifica como devolver el dato. Puede ser
de la siguiente manera:
- Nombre de la clave del array o de la propiedad del objeto para recuperar el valor.
- Conjunto de puntos separados por las claves del array o los nombres de las propiedades del objeto. Esto se ha usado en el ejemplo anterior.
- Un callback que devuelve un valor.
El callback se debería usar de la siguiente manera:
```php
$fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) {
return $user->firstName . ' ' . $user->lastName;
});
```
El tercer argumento opcional es el valor por defecto el cual es `null` si no se especifica. Podría ser utilizado de la siguiente manera:
```php
$username = ArrayHelper::getValue($comment, 'user.username', 'Unknown');
```
En caso de que quieras coger un valor y luego removerlo inmediatamente del array puedes usar el método `remove`:
```php
$array = ['type' => 'A', 'options' => [1, 2]];
$type = ArrayHelper::remove($array, 'type');
```
Después de ejecutar el código el `$array` contendrá `['options' => [1, 2]]` y `$type` debe ser `A`. Tenga en cuenta que a diferencia del método
`getValue`, `remove` solo soporta nombres clave simples.
## Comprobando la Existencia de Claves
`ArrayHelper::keyExists` funciona de la misma manera que [array_key_exists](https://www.php.net/manual/es/function.array-key-exists.php)
excepto que también soporta case-insensitive para la comparación de claves. Por ejemplo,
```php
$data1 = [
'userName' => 'Alex',
];
$data2 = [
'username' => 'Carsten',
];
if (!ArrayHelper::keyExists('username', $data1, false) || !ArrayHelper::keyExists('username', $data2, false)) {
echo "Please provide username.";
}
```
## Recuperando Columnas
A menudo necesitas obtener unos valores de una columna de las filas de datos u objetos de un array. Un ejemplo común es obtener una lista de IDs.
```php
$data = [
['id' => '123', 'data' => 'abc'],
['id' => '345', 'data' => 'def'],
];
$ids = ArrayHelper::getColumn($array, 'id');
```
El resultado será `['123', '345']`.
Si se requieren transformaciones adicionales o la manera de obtener el valor es complejo, se podría especificar como segundo argumento
una función anónima :
```php
$result = ArrayHelper::getColumn($array, function ($element) {
return $element['id'];
});
```
## Re-indexar Arrays
Con el fin de indexar un array según una clave especificada, se puede usar el método `index`. La entrada debería ser
un array multidimensional o un array de objetos. `$key` puede ser tanto una clave del sub-array, un nombre de una propiedad
del objeto, o una función anónima que debe devolver el valor que será utilizado como clave.
El atributo `$groups` es un array de claves, que será utilizado para agrupar el array de entrada en uno o más sub-arrays
basado en la clave especificada.
Si el atributo `$key` o su valor por el elemento en particular es `null` y `$groups` no está definido, dicho elemento del array
será descartado. De otro modo, si `$groups` es especificado, el elemento del array será agregado al array resultante
sin una clave.
Por ejemplo:
```php
$array = [
['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
['id' => '345', 'data' => 'def', 'device' => 'tablet'],
['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
];
$result = ArrayHelper::index($array, 'id');');
```
El resultado será un array asociativo, donde la clave es el valor del atributo `id`
```php
[
'123' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
'345' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
// El segundo elemento del array original es sobrescrito por el último elemento debido a que tiene el mismo id
]
```
Pasando una función anónima en `$key`, da el mismo resultado.
```php
$result = ArrayHelper::index($array, function ($element) {
return $element['id'];
});
```
Pasando `id` como tercer argumento, agrupará `$array` mediante `id`:
```php
$result = ArrayHelper::index($array, null, 'id');
```
El resultado será un array multidimensional agrupado por `id` en su primer nivel y no indexado en su segundo nivel:
```php
[
'123' => [
['id' => '123', 'data' => 'abc', 'device' => 'laptop']
],
'345' => [ // todos los elementos con este índice están presentes en el array resultante
['id' => '345', 'data' => 'def', 'device' => 'tablet'],
['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
]
]
```
Una función anónima puede ser usada también en el array agrupador:
```php
$result = ArrayHelper::index($array, 'data', [function ($element) {
return $element['id'];
}, 'device']);
```
El resultado será un array multidimensional agrupado por `id` en su primer nivel, por `device` en su segundo nivel e
indexado por `data` en su tercer nivel:
```php
[
'123' => [
'laptop' => [
'abc' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop']
]
],
'345' => [
'tablet' => [
'def' => ['id' => '345', 'data' => 'def', 'device' => 'tablet']
],
'smartphone' => [
'hgi' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
]
]
]
```
## Construyendo Mapas (Maps)
Con el fin de construir un mapa (pareja clave-valor) de un array multidimensional o un array de objetos puedes usar el método `map`.
Los parámetros `$from` y `$to` especifican los nombres de las claves o los nombres de las propiedades que serán configuradas en el mapa. Opcionalmente, se puede
agrupar en el mapa de acuerdo al campo de agrupamiento `$group`. Por ejemplo,
```php
$array = [
['id' => '123', 'name' => 'aaa', 'class' => 'x'],
['id' => '124', 'name' => 'bbb', 'class' => 'x'],
['id' => '345', 'name' => 'ccc', 'class' => 'y'],
);
$result = ArrayHelper::map($array, 'id', 'name');
// el resultado es:
// [
// '123' => 'aaa',
// '124' => 'bbb',
// '345' => 'ccc',
// ]
$result = ArrayHelper::map($array, 'id', 'name', 'class');
// el resultado es:
// [
// 'x' => [
// '123' => 'aaa',
// '124' => 'bbb',
// ],
// 'y' => [
// '345' => 'ccc',
// ],
// ]
```
## Ordenamiento Multidimensional
El método `multisort` ayuda a ordenar un array de objetos o arrays anidados por una o varias claves. Por ejemplo,
```php
$data = [
['age' => 30, 'name' => 'Alexander'],
['age' => 30, 'name' => 'Brian'],
['age' => 19, 'name' => 'Barney'],
];
ArrayHelper::multisort($data, ['age', 'name'], [SORT_ASC, SORT_DESC]);
```
Después del ordenado obtendremos lo siguiente en `$data`:
```php
[
['age' => 19, 'name' => 'Barney'],
['age' => 30, 'name' => 'Brian'],
['age' => 30, 'name' => 'Alexander'],
];
```
El segundo argumento que especifica las claves para ordenar puede ser una cadena si se trata de una clave, un array en caso de que tenga múltiples claves
o una función anónima como la siguiente
```php
ArrayHelper::multisort($data, function($item) {
return isset($item['age']) ? ['age', 'name'] : 'name';
});
```
El tercer argumento es la dirección. En caso de ordenar por una clave podría ser `SORT_ASC` o
`SORT_DESC`. Si ordenas por múltiples valores puedes ordenar cada valor diferentemente proporcionando un array de
direcciones de ordenación.
El último argumento es un PHP sort flag que toma los mismos valores que los pasados a
PHP [sort()](https://www.php.net/manual/es/function.sort.php).
## Detectando Tipos de Array
Es muy útil saber si un array es indexado o asociativo. He aquí un ejemplo:
```php
// sin claves especificadas
$indexed = ['Qiang', 'Paul'];
echo ArrayHelper::isIndexed($indexed);
// todas las claves son strings
$associative = ['framework' => 'Yii', 'version' => '2.0'];
echo ArrayHelper::isAssociative($associative);
```
## Codificación y Decodificación de Valores HTML
Con el fin de codificar o decodificar caracteres especiales en un array de strings con entidades HTML puedes usar lo siguiente:
```php
$encoded = ArrayHelper::htmlEncode($data);
$decoded = ArrayHelper::htmlDecode($data);
```
Solo los valores se codifican por defecto. Pasando como segundo argumento `false` puedes codificar un array de claves también.
La codificación utilizará el charset de la aplicación y podría ser cambiado pasandole un tercer argumento.
## Fusionando Arrays
```php
/**
* Fusiona recursivamente dos o más arrays en uno.
* Si cada array tiene un elemento con el mismo valor string de clave, el último
* sobrescribirá el anterior (difiere de array_merge_recursive).
* Se llegará a una fusión recursiva si ambos arrays tienen un elemento tipo array
* y comparten la misma clave.
* Para elementos cuyas claves son enteros, los elementos del array final
* serán agregados al array anterior.
* @param array $a array al que se va a fusionar
* @param array $b array desde el cual fusionar. Puedes especificar
* arrays adicionales mediante el tercer argumento, cuarto argumento, etc.
* @return array el array fusionado (los arrays originales no sufren cambios)
*/
public static function merge($a, $b)
```
## Convirtiendo Objetos a Arrays
A menudo necesitas convertir un objeto o un array de objetos a un array. El caso más común es convertir los modelos de active record
con el fin de servir los arrays de datos vía API REST o utilizarlos de otra manera. El siguiente código se podría utilizar para hacerlo:
```php
$posts = Post::find()->limit(10)->all();
$data = ArrayHelper::toArray($posts, [
'app\models\Post' => [
'id',
'title',
// el nombre de la clave del resultado del array => nombre de la propiedad
'createTime' => 'created_at',
// el nombre de la clave del resultado del array => función anónima
'length' => function ($post) {
return strlen($post->content);
},
],
]);
```
El primer argumento contiene el dato que queremos convertir. En nuestro caso queremos convertir un modelo AR `Post`.
El segundo argumento es el mapeo de conversión por clase. Estamos configurando un mapeo para el modelo `Post`.
Cada array de mapeo contiene un conjunto de mapeos. Cada mapeo podría ser:
- Un campo nombre para incluir como está.
- Un par clave-valor del array deseado con un nombre clave y el nombre de la columna del modelo que tomará el valor.
- Un par clave-valor del array deseado con un nombre clave y una función anónima que retorne el valor.
El resultado de la conversión anterior será:
```php
[
'id' => 123,
'title' => 'test',
'createTime' => '2013-01-01 12:00AM',
'length' => 301,
]
```
Es posible proporcionar una manera predeterminada de convertir un objeto a un array para una clase especifica
mediante la implementación de la interfaz [[yii\base\Arrayable|Arrayable]] en esa clase.
## Haciendo pruebas con Arrays
A menudo necesitarás comprobar está en un array o un grupo de elementos es un sub-grupo de otro.
A pesar de que PHP ofrece `in_array()`, este no soporta sub-grupos u objetos de tipo `\Traversable`.
Para ayudar en este tipo de pruebas, [[yii\helpers\ArrayHelper]] provee [[yii\helpers\ArrayHelper::isIn()|isIn()]]
y [[yii\helpers\ArrayHelper::isSubset()|isSubset()]] con la misma firma del método
[in_array()](https://www.php.net/manual/es/function.in-array.php).
```php
// true
ArrayHelper::isIn('a', ['a']);
// true
ArrayHelper::isIn('a', new(ArrayObject['a']));
// true
ArrayHelper::isSubset(new(ArrayObject['a', 'c']), new(ArrayObject['a', 'b', 'c'])
```
---
--- METRICS ---
- Files Extracted: 110
- Estimated Token Budget: ~126771 tokens
- Canonical Reference: https://codewiki.google/github.com/yiisoft/yii2
