День 20 Плагіни (1)

Вчора Ви навчилися інтернаціоналізувати та локалізувати Ваші програми на Symfony. Ще раз, завдяки стандартам ICU та безлічі помічників, фреймворк Symfony робить це справді простим.

Сьогодні ми поговоримо про плагіни: що вони являють собою, що Ви можете упаковати в плагін, і для чого вони можуть використовуватися.

Плагін Symfony

Плагін Symfony пропонує спосіб упаковки та розповсюдження підмножини файлів вашого проекту. Як і проект, плагін може містити класи, помічники, конфігурацію, завдання, модулі, схеми та навіть стилі (CSS) та картинки.

Приватні плагіни

Для початку плагіни використовуються для спрощення спільного використання у ваших додатках, або навіть різних проектах. Згадаймо, що програми Symfony поділяють лише модель. Плагіни надають спосіб спільного використання більшої кількості компонентів у різних додатках.

Якщо Вам потрібно повторно використовувати ту ж схему для іншого проекту або ті ж модулі, перемістіть їх у плагін. Оскільки плагін це просто папка, Ви можете підключати їх досить просто за допомогою створення SVN-сховища, використовуючи svn:externals або просто копіюючи файли з одного проекту в інший.

Ми називаємо ці плагіни "приватними" тому, що їх використання обмежене одним розробником чи компанією. Вони не доступні привселюдно.

Ви можете навіть створити пакет з приватних плагінів, створити власний канал плагінів Symfony і встановлювати їх за допомогою завдання plugin:install .

Публічні плагіни

Публічні плагіни доступні для скачування та встановлення всієї спільноти. Протягом цього навчання ми використовували кілька публічних плагінів: sfGuardPlugin та sfFormExtraPlugin.

Вони такі саміяк і приватні плагіни. Єдина відмінність це те, що будь-хто може встановити їх для своїх проектів. Пізніше Ви дізнаєтесь як публікувати та розміщувати публічні плагіни на веб-сайті Symfony.

Різні способи організації коду

Є ще один спосіб сприйняття та використання плагінів. Забудьте про повторне використання та спільне використання. Плагіни можуть бути використані для іншого способу організації коду. Замість організації файлів за рівнями: усі моделі у папці lib/model/ , шаблони у папці templates/ , . ; файли групуються за функціональністю: всі файли, що відносяться до вакансій, разом (модель, модулі та шаблони), всі файли CMS разом, і таке інше.

Структура файлів плагіна

Плагін - це структура папок з файлами, організована певним чином, залежно від характеристик файлів. Сьогодні ми перемістимо більшість коду, який ми написали для Jobeet у sfJobeetPlugin . Простий макет, який ми будемо використовувати:

Плагін Jobeet

На початку просто створимо нову папку в plugins/. Для Jobeet, давайте створимо папку sfJobeetPlugin :

Примітка: Activate sfJobeetPlugin в config/ProjectConfiguration.class.php file.

Назви всіх плагінів мають закінчуватися на Plugin. Також гарна звичка ставити для них префікс sf, але це не обов'язково.

Спочатку перемістіть файл config/schema.yml до plugins/sfJobeetPlugin/config/ :

Усі командні рядки наведені для Unix-подібного оточення. Якщо ви використовуєте Windows, можна перетягнути файли в експлорері. І якщо Ви використовуєте Subversion, або якийсь інший інструмент для керування кодом, використовуйте надані вбудовані інструменти (наприклад svn mv для переміщення файлів).

Перемістіть файли моделі, форм, тафільтрів у plugins/sfJobeetPlugin/lib/ :

Remove plugins/sfJobeetPlugin/lib/form/BaseForm.class.php file.

Якщо Ви зараз запустите завдання propel:build-model, Symfony згенерує файли в lib/model/, але це не те, чого ми хочемо. Папка виводу для Propel може бути налаштована за допомогою додавання опції package. Відкрийте schema.yml і додайте наступне налаштування:

Тепер Symfony створюватиме ці файли в папці plugins/sfJobeetPlugin/lib/model/ . Побудовник форм і фільтрів також приймає це налаштування під час генерації файлів.

Завдання propel:build-sql генерує файли SQL для створення таблиць. Оскільки файли називаються як і пакети, видаліть поточний файл:

Тепер, якщо ви запустите propel:build-all-load, Symfony буде генерувати файли в папці плагіна lib/model/ як і очікувалося:

Після запуску завдання, перевірте, що папка lib/model/ не була створена. Проте завдання створило папки lib/form/ і lib/filter/. Вони обидві включають базові класи для всіх форм Propel у вашому проекті.

Оскільки ці файли є глобальними для проекту, видаліть їх з плагіна:

Якщо ви використовуєте Symfony 1.2.0 або 1.2.1, базовий клас фільтрів форм знаходиться в папці plugins/sfJobeetPlugin/lib/filter/base/ .

Ви можете також перенести файл Jobeet.class.php в плагін:

Оскільки ми переміщували файли, очистіть кеш:

Якщо Ви використовуєте PHP-прискорювач такий як APC і відбувається щось дивне на цьому кроці, перезапустіть Apache.

Тепер, коли всі файли моделі переміщені в плагін, запустіть тести, щоб перевірити, що все працює:

Контролери та уявлення

Наступний логічний крок - це перемістити модулі в плагін. Для запобігання колізіям у назвах модулів, непогано додавати доназві модуля такий самий префікс, як і назва плагіна:

Для кожного модуля Ви також повинні змінити назви класів у всіх файлах actions.class.php і components.class.php (наприклад, клас affiliateActions потрібно перейменувати на sfJobeetAffiliateActions ).

Виклики include_partial() і include_component() повинні бути так само змінені в наступних шаблонах:

  • sfJobeetAffiliate/templates/_form.php (змініть affiliate на sfJobeetAffiliate )
  • sfJobeetCategory/templates/showSuccess.atom.php
  • sfJobeetCategory/templates/showSuccess.php
  • sfJobeetJob/templates/indexSuccess.atom.php
  • sfJobeetJob/templates/indexSuccess.php
  • sfJobeetJob/templates/searchSuccess.php
  • sfJobeetJob/templates/showSuccess.php
  • apps/frontend/templates/layout.php

Обновіть дії search і delete:

Тепер оновіть файл routing.yml, щоб застосувати ці зміни:

які говорять, що модулі не включені. Оскільки плагіни є спільними для всіх програм у проекті, Вам потрібно спеціально включити модулі, які Вам потрібні для цієї програми в його файлі налаштувань settings.yml :

Останній крок міграції – це виправлення функціональних тестів, де ми тестуємо назву модуля.

Завдання можуть бути переміщені в плагін досить легко:

Файли i18n

Плагін може також містити файли XLIFF:

Маршрутизація

Плагін може також містити правила маршрутизації:

Веб-вміст

Користувач

Переміщення методів класу myUser, які мають справу з історією вакансій, трохи складніше. Ми можемо створити клас JobeetUser і зробити так, щоб клас myUser успадковувався від нього. Але є краще рішення, особливо якщо кілька плагінівхочуть додати методи до класу.

Об'єкти ядра Symfony сповіщають про події протягом їхнього життєвого циклу, і Ви можете їх слухати. У нашому випадку потрібно слухати подію user.method_not_found, яка відбувається коли викликається метод, не визначений в об'єкті sfUser.

Коли Symfony ініціалізований, всі плагіни теж ініціалізовані, якщо вони мають клас конфігурації плагіна:

Оповіщення про події управляється за допомогою sfEventDispatcher об'єкта диспечера подій. Реєстрація слухача така ж проста, як і виклик методу connect() . Метод connect() підключає назву події до PHP-об'єктів, що викликаються.

PHP-об'єкт, що викликається, це змінна PHP яка може бути використана функцією call_user_func() і повертає true коли буде передана в функцію is_callable() . Рядок представляє функцію, а масив може представляти метод об'єкта або метод класу.

За допомогою наступного коду об'єкт myUser буде викликати статичний метод methodNotFound() класу JobeetUser щоразу, коли не зможе знайти метод. Після цього все залежить від методу methodNotFound() - обробляти пропущений метод чи ні.

Видаліть усі методи з класу myUser та створіть клас JobeetUser :

Коли диспечер викликає метод methodNotFound() , він передасть об'єкт sfEvent .

Якщо метод існує в класі JobeetUser , він буде викликаний, і його значення, що повертається, буде передано далі до реєстратора. Якщо ні, Symfony намагатиметься знайти наступний слухач або поверне виняток.

Метод getSubject() повертає реєстратора події, у разі це об'єкт myUser .

Структура за промовчанням проти архітектури плагіна

Використання архітектури плагіна дає Вам можливість організувати Ваш код іншим способом:

плагіни

Використання плагінів

Коли Ви починаєте впроваджувати нову функціональність, або якщо Ви намагаєтеся вирішити класичну проблему веб-програмування, можливо, хтось інший вже вирішив таку ж проблему і можливо запакував рішення як плагін Symfony. Подивіться у публічних плагінах Symfony у секції плагінів на сайті фреймворку Symfony.

Оскільки плагін - це самодостатня папка, є кілька способів його встановлення:

  • Використовуючи завдання plugin:install (працює лише якщо розробник плагіна створив пакет плагіна та завантажив його на веб-сайт Symfony)
  • Завантажте пакет і вручну розпакуйте його в папку plugins/ (також потрібно, щоб розробник завантажив пакет)
  • Створення svn:externals в plugins/ для плагіна (працює тільки якщо розробник плагіна хостить цей плагін Subversion)

Останні два способи прості, але їм не вистачає гнучкості. Перший спосіб дозволяє Вам встановити останню версію в залежності від версії Symfony у проекті, легко оновити до останнього стабільного релізу та легше керувати залежностями між плагінами.

Створення плагіна

Упаковка плагіна

Для створення пакета плагіна потрібно додати деякі обов'язкові файли в структуру папок плагіна. Спочатку створіть файл README у кореневій папці плагіна та опишіть як встановити плагін, що він надає та що ні. Файл README має бути відформатований у форматі Markdown. Цей файл буде використаний веб-сайтом Symfony як основна частина документації. Ви можете протестувати трансформацію вашого файлу README в HTML, використовуючи Symfony plugin dingus.

Розробка завдань плагіна

Якщо Ви виявите, що Ви часто створюєте приватні та/або публічні плагіни, скористайтесь перевагами деяких завдань уsfTaskExtraPlugin. Цей плагін, що підтримується розробниками ядра Symfony, включає низку завдань, які допоможуть Вам спростити життєвий цикл плагіна:

Вам також потрібно створити файл LICENSE. Вибір ліцензії не проста задача, але в секції плагінів Symfony показуються лише плагіни, випущені під ліцензією подібної ліцензії Symfony (MIT, BSD, LGPL, and PHP). Вміст файлу LICENSE буде відображено на вкладці ліцензії публічної сторінки вашого плагіна.

Останнім кроком є ​​створення файлу package.xml у кореневій папці плагіна. Цей файл package.xml відповідає синтаксису PEAR.

Найкращий спосіб вивчити синтаксис package.xml – це скопіювати його з існуючого плагіна.

Як ви бачите в цьому прикладі, файл package.xml складається з кількох частин:

Тег містить файли, які потрібно помістити в пакет:

Тег вказує всі залежності, які можуть бути у плагіну: PHP, symfony, а також інші плагіни. Ця інформація використовується завданням plugin:install для встановлення найвідповіднішої версії плагіна для оточення проекту, і так само встановлює плагіни, необхідні в залежності якщо вони є.

Ви повинні завжди вказувати залежність від Symfony, як ми зробили тут. Заява мінімальної та максимальної версії дає можливість задачі plugin:install дізнатися, яка версія Symfony є обов'язковою, оскільки різні версії фреймворку мають дуже різні API.

Також можлива заява залежностей від інших плагінів:

Тег є опціональним, але дає корисну інформацію про те, що було змінено між релізами. Ця інформація також доступна на вкладці "Changelog" і у стрічці плагінів.

Розміщення плагінів на веб-сайті Symfony

Ви автоматично станете адміністратором для плагіна та побачите вкладку "admin" в інтерфейсі. В ційвкладці Ви знайдете все, що потрібно для керування Вашим плагіном та завантаження Ваших пакетів.

FAQ з плагінів містить багато корисної інформації для розробників плагінів.

Побачимося завтра!

Створення плагінів та спільне їх використання у спільноті - це один із найкращих способів зробити внесок у проект Symfony. Це настільки просто, що сховище плагінів заповнене корисними, кумедними, а іноді й безглуздими плагінами.

Symfony™ є trademark of Symfony SAS. Всі права захищені.