Управління URL ============== Управління URL-адресами у веб-додатках включає у себе два аспекти: 1. Додатку необхідно розібрати запит користувача, що надходить у вигляді URL, на окремі параметри. 2. Додаток повинен надавати спосіб формування адрес URL, з якими воно зможе коректно працювати. У додатках на Yii ці завдання вирішуються з використанням класу [CUrlManager]. > Note|Примітка: Ви можете не користуватися Yii для генерації URL, однак, так робити не рекомендується, тому що ви не зможете легко поміняти URL додатка через конфігурацію без зміни коду. Створення адрес URL ------------------- В принципі, адреси URL можна задати прямо в коді представлень контролера, проте куди зручніше створювати їх динамічно: ~~~ [php] $url=$this->createUrl($route,$params); ~~~ де `$this` відноситься до екземпляра контролера; `$route` відповідає [маршруту](/doc/guide/basics.controller#route) запиту, а `$params` є списком параметрів `GET` для додавання до URL. За замовчуванням, адреси створюються за допомогою [createUrl|CController::createUrl] в `get`-форматі. Наприклад, при значеннях параметрів `$route='post/read'` і `$params=array('id'=>100)`, отримаємо такий URL: ~~~ /index.php?r=post/read&id=100 ~~~ де параметри зазначені у вигляді набору пар `імʼя=значення`, зʼєднаних знаком `&`, а параметр `r` вказує на [маршрут](/doc/guide/basics.controller#route). Однак, цей формат не дуже дружелюбний по відношенню до користувача. > Tip|Підказка: Для того, щоб згенерувати URL з хештегом, наприклад, `/index.php?r=post/read&id=100#title`, необхідно передати параметр `#` наступним чином: `$this->createUrl('post/read',array('id'=>100,'#'=>'title'))`. Ми можемо зробити так, щоб адреса, наведена у якості приклада вище, виглядала більш акуратно і зрозуміло за рахунок використання формату `path`, який виключає використання рядка запиту і включає всі GET-параметри в інформаційну частину адреси URL: ~~~ /index.php/post/read/id/100 ~~~ Для зміни формату представлення адреси URL, потрібно налаштувати компонент додатка [urlManager|CWebApplication::urlManager] таким чином, щоб метод [createUrl|CController::createUrl] міг автоматично переключитися на використання нового формату, а додаток міг коректно сприймати новий формат адрес URL: ~~~ [php] array( … 'components'=>array( … 'urlManager'=>array( 'urlFormat'=>'path', ), ), ); ~~~ Зверніть увагу, що вказувати клас компонента [urlManager|CWebApplication::urlManager] не потрібно, тому що він вже оголошений як [CUrlManager] в [CWebApplication]. > Tip|Підказка: Адреса URL, генерована методом [createUrl|CController::createUrl] є відносним. Для того, щоб отримати абсолютну адресу, потрібно додати префікс, використовуючи `Yii::app()->request->hostInfo`, або викликати метод [createAbsoluteUrl|CController::createAbsoluteUrl]. Людинозрозумілі URL ------------------- Якщо у якості формата адреси URL використовується `path`, то ми можемо визначити правила формування URL, щоб зробити адреси більш привабливими і зрозумілими з точки зору користувача. Наприклад, ми можемо використовувати коротку адресу `/post/100` замість довгого варіанту `/index.php/post/read/id/100`. [CUrlManager] використовує правила формування URL як для створення, так і для обробки адрес. Правила формування URL задаються шляхом конфігурації властивості [rules|CUrlManager::rules] компонента додатку [urlManager|CWebApplication::urlManager]: ~~~ [php] array( … 'components'=>array( … 'urlManager'=>array( 'urlFormat'=>'path', 'rules'=>array( 'pattern1'=>'route1', 'pattern2'=>'route2', 'pattern3'=>'route3', ), ), ), ); ~~~ Правила задаються у вигляді масиву пар шаблон-шлях, де кожна пара відповідає одному правилу. Шаблон правила - рядок, який повинен збігатися із шляхом в URL. Шлях правила повинен вказувати на існуючий [шлях контролера](/doc/guide/basics.controller#route). Крім показаного вище способу завдання правил, можна описати правило із зазначенням додаткових параметрів: ~~~ [php] 'pattern1'=>array('route1', 'urlSuffix'=>'.xml', 'caseSensitive'=>false) ~~~ Починаючи з версії 1.1.7, можна використовувати показаний нижче формат. Тобто патерн вказується як елемент масиву, що дозволяє вказати кілька правил одного патерну: ~~~ [php] array('route1', 'pattern'=>'pattern1', 'urlSuffix'=>'.xml', 'caseSensitive'=>false) ~~~ Тут масив містить список додаткових параметрів для правила. Можливо вказати наступні параметри: - [pattern|CUrlRule::pattern]: патерн, який буде використаний при зіставленні і створенні URL. Дана можливість доступна з версії 1.1.7. - [urlSuffix|CUrlRule::urlSuffix]: суфікс URL, який використовується виключно для даного правила. За замовчуванням дорівнює null, що означає використання значення [CUrlManager::urlSuffix]. - [caseSensitive|CUrlRule::caseSensitive]: чи враховує правило регістр. За замовчуванням дорівнює null, що означає використання значення [CUrlManager::caseSensitive]. - [defaultParams|CUrlRule::defaultParams]: GET-параметри за замовчуванням (`імʼя=>значення`) для даного правила. При спрацьовуванні правила параметри будуть додані в `$_GET`. - [matchValue|CUrlRule::matchValue]: чи повинні значення GET-параметрів при створенні URL збігатися з відповідними підвиразами в основному правилі. За замовчуванням дорівнює null, що означає використання значення [CUrlManager::matchValue]. При значенні параметра `false` правило буде використано для створення URL тільки якщо імена параметрів збігаються з іменами в правилі. При значенні `true` значення параметрів додатково повинні збігатися з підвиразами у правилі. Варто зазначити, що установка значення в `true` знижує продуктивність. - [verb|CUrlRule::verb]: тип HTTP запиту (наприклад, `GET`, `POST`, `DELETE`), для якого працює дане правило. За замовчуванням дорівнює null, що означає роботу правила з будь-якими HTTP запитами. Якщо необхідно вказати кілька типів запитів, їх треба розділити комами. У тому випадку, коли правило не збігається з поточним типом запиту, воно пропускається на етапі розбору запиту. Дана опція використовується тільки для розбору запиту і введена для підтримки URL у стилі REST. Дана можливість доступна з версії 1.1.7. - [parsingOnly|CUrlRule::parsingOnly]: чи використовувати правило тільки на етапі розбору запиту. За замовчуванням дорівнює `false`, що означає, що правило використовується як для розбору запиту, так і для побудови URL. Дана можливість доступна з версії 1.1.7. Використання іменованих параметрів ---------------------------------- Правило може бути асоційоване з кількома GET-параметрами. Ці параметри вказуються у шаблоні правила у вигляді маркерів наступним чином: ~~~ ~~~ де `ParamName` відповідає імені GET-параметра, а необовʼязковий `ParamPattern` - регулярному виразу, який використовується для перевірки відповідності значенню GET-параметра. Якщо `ParamPattern` не зазначений, то параметр повинен відповідати будь-яким символам, крім слеша `/`. У момент створення URL маркери будуть замінені на відповідні значення параметрів, а в момент обробки URL, відповідним GET-параметрами будуть присвоєні результати обробки. Для наочності наведемо кілька прикладів. Припустимо, що наш набір правил складається з трьох правил: ~~~ [php] array( 'posts'=>'post/list', 'post/'=>'post/read', 'post//'=>'post/read', ) ~~~ - Виклик `$this->createUrl('post/list')` згенерує `/index.php/posts`. Тут було застосовано перше правило. - Виклик `$this->createUrl('post/read',array('id'=>100))` згенерує `/index.php/post/100`. Застосовано друге правило. - Виклик `$this->createUrl('post/read',array('year'=>2008,'title'=>'a sample post'))` згенерує `/index.php/post/2008/a%20sample%20post`. Використано третє правило. - Виклик `$this->createUrl('post/read')` згенерує `/index.php/post/read`. Жодне з правил не було застосовано. При використанні [createUrl|CController::createUrl] для генерації адреси URL, маршрут і GET-параметри, передані методу, використовуються для визначення правила, яке потрібно застосувати. Правило застосовується у тому випадку, коли всі параметри, асоційовані з правилом, присутні серед GET-параметрів, а маршрут відповідає параметру маршруту. Якщо ж кількість GET-параметрів більше, ніж вимагає правило, то зайві параметри будуть включені до рядка запиту. Наприклад, якщо викликати `$this->createUrl('post/read',array('id'=>100,'year'=>2008))`, ми отримаємо `/index.php/post/100?year=2008`. Для того, щоб зайві параметри були відображені в інформаційній частині шляху, необхідно додати до правила `/*`. Таким чином, використовуючи правило `post/<id:\d+>/*` отримаємо URL вигляду `/index.php/post/100/year/2008`. Як вже говорилося, друге завдання правил URL - розбирати URL-запити. Цей процес зворотний процесу створення URL. Наприклад, коли користувач запитує `/index.php/post/100`, застосовується друге правило з прикладу вище і запит перетворюється в маршрут `post/read` і GET-параметр `array('id'=>100)` (доступний через `$_GET`). > Note|Примітка: Використання правил URL знижує продуктивність додатку. Це відбувається з тієї причини, що у процесі парсинга запитаного URL [CUrlManager] намагається знайти відповідність кожного правила до тих пір, поки яке-небудь з правил не буде застосовано. Чим більше правил, тим більше втрати продуктивності. Тому у разі високонавантажених додатків використання правил URL варто мінімізувати. Параметризація маршрутів ------------------------ Ми можемо використовувати іменовані параметри у маршруті правила. Таке правило може бути застосоване до декількох маршрутах, що збігаються з правилом. Це може допомогти зменшити число правил і, таким чином, підвищити продуктивність додатку. Для того, щоб показати параметризацію маршрутів, використовуємо наступний набір правил: ~~~ [php] array( '<_c:(post|comment)>/<id:\d+>/<_a:(create|update|delete)>' => '<_c>/<_a>', '<_c:(post|comment)>/<id:\d+>' => '<_c>/read', '<_c:(post|comment)>s' => '<_c>/list', ) ~~~ Ми використовували два іменованих параметри в маршруті правил: `_c` і `_a`. Перший відповідає назві контролера і може дорівнювати `post` або `comment`, другий - назві action-а і може приймати значення `create`, `update` або `delete`. Ви можете називати параметри по-іншому, якщо їх імена не конфліктують з GET-параметрами, які можуть використовуватися в URL. При використанні правил, наведених вище, URL `/index.php/post/123/create` буде оброблено як маршрут `post/create` з GET-параметром `id=123`. По маршруту `comment/list` з GET-параметром `page=2`, ми можемо створити URL `/index.php/comments?page=2`. Параметризація імен хостів -------------------------- Також можливо використовувати імена хостів в правилах для розбору і створення URL. Можна виділяти частину імені хоста в GET-параметр. Наприклад, URL `http://admin.example.com/en/profile` може бути розібраний в GET-параметри `user=admin` і `lang=en`. З іншого боку, правила з іменами хостів можуть також використовуватися для створення URL адрес. Щоб використовувати параметризрвані імена хостів, увімкніть імʼя хоста у правила URL: ~~~ [php] array( 'http://<user:\w+>.example.com/<lang:\w+>/profile' => 'user/profile', ) ~~~ Приклад вище говорить, що перший сегмент імені хоста повинен стати параметром `user`, а перший сегмент шляху — параметром `lang`. Правило відповідає маршруту `user/profile`. Памʼятайте, що [CUrlManager::showScriptName] не працює при створенні URL адреси з використанням правил з параметризованим імʼям хоста. Варто відзначити, що правило з параметризованим імʼям хоста не повинно містити піддиректорій у тому випадку, якщо додаток знаходиться у піддиректорії кореня веб-сервера. Приміром, якщо додаток розташовується за адресою `http://www.example.com/sandbox/blog`, ми повинні використовувати точно таке ж правило URL, як описано вище. Без піддиректорії: `sandbox/blog`. Приховуємо `index.php` ---------------------- З метою зробити адресу URL ще більш привабливою можна сховати імʼя вхідного скрипта `index.php`. Для цього необхідно налаштувати веб-сервер і компонент додатку [urlManager|CWebApplication::urlManager]. Спочатку зконфігуруємо веб-сервер таким чином, щоб адреса URL без вказівки імені вхідного скрипта як і раніше передавався на обробку вхідного скрипта. Для сервера [Apache HTTP server](http://httpd.apache.org/) це досягається шляхом включення механізму перетворення URL і завданням кількох правил. Для цього необхідно створити файл `/wwwroot/blog/.htaccess`, що містить правила, наведені нижче. Ті ж правила можуть бути розміщені у файлі конфігурації Apache в секції `Directory` для `/wwwroot/blog`. ~~~ RewriteEngine on # if a directory or a file exists, use it directly RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d # otherwise forward it to index.php RewriteRule . index.php ~~~ Далі потрібно встановити властивість [showScriptName|CUrlManager::showScriptName] компонента [urlManager|CWebApplication::urlManager] рівним `false`. Тепер, викликавши `$this->createUrl('post/read',array('id'=>100))`, ми отримаємо URL `/post/100`. Що важливо, ця адреса URL буде коректно розпізнана нашим веб-додатком. Підміна закінчення у адресі URL ------------------------------- На додаток до всього перерахованого вище, ми можемо додати до наших адрес URL закінчення. Наприклад, ми можемо отримати `/post/100.html` замість `/post/100`, представивши користувачеві начебто статичну сторінку. Для цього потрібно просто налаштувати компонент [urlManager|CWebApplication::urlManager] шляхом встановлення властивості [urlSuffix|CUrlManager::urlSuffix] будь-якого бажаного закінчення. Використання свого класу правила URL ------------------------------------ > Note|Примітка: дана можливість доступна з версії 1.1.8. За замовчуванням кожне правило URL для [CUrlManager] представлено обʼєктом класу [CUrlRule]. Цей обʼєкт розбирає запити і створює URL по заданому правилу. Незважаючи на те, що [CUrlRule] досить гнучкий і підходить для роботи із більшістю форматів URL, іноді потрібні які-небудь особливі можливості. Наприклад, для сайту з продажу автомобілів може знадобитися підтримувати URL виду `/Виробник/Модель`, де і `Виробник` і `Модель` повинні відповідати даним з певної таблиці бази даних. У цьому випадку клас [CUrlRule] не підійде так як він, в основному, працює із статично описаними регулярними виразами, а не з базою даних. У даному випадку можна реалізувати новий клас правила URL, успадкувавши [CBaseUrlRule], і використовувати його в одному або декількох правилах. Для наведеного вище прикладу з продажу автомобілів підійдуть такі правила URL: ~~~ [php] array( // стандартне правило для обробки '/' як 'site/index' '' => 'site/index', // стандартне правило для обробки '/login' як 'site/login' і т.д. '<action:(login|logout|about)>' => 'site/<action>', // власне правило для URL вигляду '/Виробник/Модель' array( 'class' => 'application.components.CarUrlRule', 'connectionID' => 'db', ), // стандартне правило для обробки 'post/update' та ін. '<controller:\w+>/<action:\w+>' => '<controller>/<action>', ), ~~~ Вище ми використали свій клас правила URL `CarUrlRule` для обробки URL вигляду `/Виробник/Модель`. Даний клас може бути реалізований наступним чином: ~~~ [php] class CarUrlRule extends CBaseUrlRule { public $connectionID = 'db'; public function createUrl($manager,$route,$params,$ampersand) { if ($route==='car/index') { if (isset($params['manufacturer'], $params['model'])) return $params['manufacturer'] . '/' . $params['model']; else if (isset($params['manufacturer'])) return $params['manufacturer']; } return false; // не застосовуємо дане правило } public function parseUrl($manager,$request,$pathInfo,$rawPathInfo) { if (preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)) { // Перевіряємо $matches[1] і $matches[3] на предмет // відповідності виробнику і моделі у БД. // Якщо відповідають, виставляємо $_GET['manufacturer'] та/або $_GET['model'] // і повертаємо рядок із маршрутом 'car/index'. } return false; // не застосовуємо дане правило } } ~~~ Свій клас правила URL повинен реалізувати два абстрактних методи, оголошених у [CBaseUrlRule]: * [createUrl()|CBaseUrlRule::createUrl()] * [parseUrl()|CBaseUrlRule::parseUrl()] Крім показаного вище типового використання, свій клас URL може стати у нагоді і в інших ситуаціях. Наприклад, можна реалізувати клас правила, який буде записувати у журнал адреси URL, що розбираються і створюються. Це може стати у нагоді на етапі розробки. Також можна реалізувати клас, який показує особливу сторінку помилки 404 у тому випадку, коли всі інші правила не спрацювали для адреси URL, що розбирається. Варто зазначити, що в цьому випадку правило з цим спеціальним класом повинно вказуватися останнім у списку.