Гостьова книга, крок 4: функції і шаблони
Мета
Застосувати функції у справжньому проєкті: винести обчислення гостьової книги у функції з типами параметрів і результату в строгому режимі, записи — у файл даних з return [...], а шапку й підвал — у шаблони, і підключити все через require і __DIR__ з-поза веб-кореня. Навчитися рефакторингу — змінювати будову коду, не змінюючи сторінку, — і доводити це порівнянням HTML до і після. Знаходити типові помилки з функціями: неправильний шлях у require, рядок замість int у строгому режимі й забутий return.
Завдання
Продовжуємо проєкт із кроку 3 — практики «Гостьова книга, крок 3: записи в масиві». Уся книга зараз — один файл src/public/guestbook/index.php на двісті рядків, де дані, обчислення й HTML упереміш. У цьому кроці сторінка в браузері не зміниться ані на символ — зміниться будова коду. Таку зміну називають рефакторингом (refactoring).
Має вийти:
src/guestbook/functions.php—declare(strict_types=1)і вісім функцій із типами:greeting(),pluralEntries(),ratingLabel(),ratingClass(),stars(),averageRating(),pagesCount()іpageEntries(); без викликів і виводу;src/guestbook/data.php— сім записів із кроку 3, які файл повертає черезreturn [...];src/guestbook/templates/header.phpіfooter.php— шапка й підвал сторінки;index.phpпідключає їх черезrequireі__DIR__, а сам лише читає адресний рядок, викликає функції й виводить записи;- HTML сторінки — той самий, що після кроку 3, а
http://localhost:8080/guestbook/functions.phpвіддає 404: функції, дані й шаблони лежать поза веб-коренем.
intita-php/
└── src/
├── guestbook/ ← нове: поза веб-коренем
│ ├── functions.php
│ ├── data.php
│ └── templates/
│ ├── header.php
│ └── footer.php
└── public/
└── guestbook/
├── index.php ← коротшає
└── style.css ← без змін
Форма нового запису поки нічого не зберігає: приймати її дані навчимося в модулі 10 «Форми: GET і POST». Теорія — у лекціях «Функції: параметри і return» і «Типи, include і require: код у кількох файлах».
Кроки
-
Знімок «до». Запустіть робочий проєкт
intita-php(docker compose up -d) і відкрийтеhttp://localhost:8080/guestbook/— сторінка з кроку 3 має працювати. Перш ніж щось змінювати, збережіть HTML двох сторінок у папку надintita-php: вона поза репозиторієм, тож файли не потраплять у коміт. Команди виконуйте з папкиintita-php:curl -s "http://localhost:8080/guestbook/?hour=20" -o ../step3-hour20.html curl -s "http://localhost:8080/guestbook/?page=2&hour=20" -o ../step3-page2.html-oзаписує відповідь у файл, а-sприбирає індикатор завантаження.?hour=20фіксує привітання: без нього воно залежало б від години, і порівняння в різний час показало б різницю. З цими файлами ви порівняєте сторінку після рефакторингу в кроці 10. -
Папки поза веб-коренем. Створіть папку
src/guestbook/, а в ній —templates/: поруч ізsrc/public/, а не всередині. Корінь сайту для nginx —src/public/, і файл поза ним браузер не відкриє: так було зsrc/test.phpу практиці «Практика: розгортаємо середовище PHP-розробника». А PHP підключає файли звідки завгодно. У контейнеріphpпапкаsrc/— це/var/www/html. -
Записи — у
data.php. Створітьsrc/guestbook/data.phpі перенесіть у нього зindex.phpмасив записів. Замість коментаря й$entries = [поставте два рядки коментаря іreturn [, решта масиву — без змін:<?php // Записи гостьової книги: від найстаршого до найновішого, новий запис стане в кінець. // Лише дані, без виводу: файл повертає масив тому, хто його підключає через require return [ [ 'id' => 1, 'name' => "Олена",… і так до
];. Вindex.phpна місці масиву лишіть два рядки:// Записи книги — з файлу даних src/guestbook/data.php, від найстаршого до найновішого $entries = require __DIR__ . '/../../guestbook/data.php';returnпоза функцією віддає значення тому, хто підключав файл, іrequireкладе масив у$entries.__DIR__вindex.php— це/var/www/html/public/guestbook: перший..піднімає вpublic, другий — у/var/www/html, тобто вsrc/, а звідти шлях веде вguestbook/data.php.
Оновіть сторінку: записи на місці.
-
Файл функцій і строгий режим. Створіть
src/guestbook/functions.php:<?php, другим рядкомdeclare(strict_types=1);, а після порожнього рядка — коментар// Функції гостьової книги: лише оголошення — без викликів і виводу. Вindex.phpвставтеdeclare(strict_types=1);другим рядком, одразу після<?php: режим діє на виклики з того файлу, де його оголошено, а функції викликатиме самеindex.php. Під ним — порожній рядок і коментар// Гостьова книга, крок 4: функції і шаблонизамість коментаря кроку 3, а нижче — підключення файлу функцій:// Функції книги — поза веб-коренем, у src/guestbook/functions.php require_once __DIR__ . '/../../guestbook/functions.php';require_once— бо файл із функціями, підключений удруге, зупинив би сторінку зCannot redeclare function.- Дані з адресного рядка — рядки, але
(int)у$hourі$pageуже робить із них числа, тож строгий режим сторінку не зламає.
-
Перша функція:
greeting(). Блок// Привітання за годиною…перенесіть уfunctions.phpяк функцію: кожна гілка тепер не присвоює, а повертає./** * Привітання за годиною 0–23: «Доброго ранку», «Доброго дня», «Доброго вечора» чи «Доброї ночі». */ function greeting(int $hour): string { // Ніч — два проміжки, далі пороги від більшого до меншого if ($hour < 5 || $hour >= 23) { return "Доброї ночі"; } if ($hour >= 18) { return "Доброго вечора"; } if ($hour >= 12) { return "Доброго дня"; } return "Доброго ранку"; }- Ранній
returnзаміняєelseif: щойно відповідь відома, функція виходить. - В
index.phpзамість блоку лишіть два рядки:// Привітання за годиною — його показує шапкаі$greeting = greeting($hour);. - Так оформлюйте кожну функцію цього кроку: doc-коментар
/** … */з одним реченням про те, що вона повертає, і тип кожного параметра й результату.
- Ранній
-
Оцінка запису:
ratingLabel(),ratingClass()іstars(). Циклforeach ($pageEntries as $i => $entry)з кроку 3 дописував у кожен запис сторінки зірки, підпис і назву стилю. Тепер із трьох його частин вийдуть три функції з параметромint $ratingі результатомstring:ratingLabel()—return match ($rating) { … };з першимmatchциклу;ratingClass()— так само з другимmatch, з назвами стилівrating-good,rating-ok,rating-badіrating-none;stars()— накопичувач$stars = "";, циклfor, у якому замість$entry['rating']— параметр$rating, іreturn $stars;.
Сам цикл разом із двома рядками коментаря над ним з
index.phpвидаліть. У шаблоні викличте функції прямо в<?= ?>:<?= ratingClass($entry['rating']) ?>,<?= stars($entry['rating']) ?>і<?= ratingLabel($entry['rating']) ?>замість$entry['ratingClass'],$entry['stars']і$entry['ratingLabel']— так само, якpriceTag()у шаблоні лекції «Типи, include і require: код у кількох файлах». Проблеми з копією$entryбільше немає: функції не змінюють масив, а повертають значення. -
Підпис кількості:
pluralEntries(). Блок// Форма слова «запис»…стає функцієюpluralEntries(int $count): string, яка повертає число разом зі словом:pluralEntries(21)→21 запис,pluralEntries(12)→12 записів.- Тіло — ті самі
$lastDigit,$lastTwoDigitsіmatch (true), але від$count, а не від$entriesCount. Результатmatchпокладіть у$word, а поверніть"$count $word". - В
index.phpблок видаліть, а в шаблоні<?= $entriesCount ?> <?= $entriesWord ?>замініть на<?= pluralEntries($entriesCount) ?>. - «Записів ще немає» лишається в шаблоні: для 0 функція поверне
0 записів.
- Тіло — ті самі
-
Середня й сторінки.
averageRating(array $entries): float— замість тернарного оператора раннійreturn: для порожнього масивуreturn 0.0;, інакшеarray_sum(array_column($entries, 'rating')) / count($entries). Ділення цілих буває цілим (20 / 5дає4), але тип результатуfloatперетворює його на4.0: таке перетворення строгий режим дозволяє. Вindex.phpпід коментарем// Середня оцінка; у порожній книзі — 0лишіть$averageRating = averageRating($entries);.pagesCount(int $count, int $perPage): int— блокintdiv()іifз кроку 2, що повертає кількість сторінок. Вindex.phpпід тим самим коментарем:$pagesCount = pagesCount($entriesCount, $perPage);.- Межі
$page— дваifз кроку 3 — лишаються вindex.php: вони змінюють$page, а поточна сторінка потрібна навігації. pageEntries(array $entries, int $page, int $perPage): array—array_reverse()іarray_slice()з кроку 3. Вindex.phpпід коментарем// Записи сторінки: найновіші першими, $perPage штук:$pageEntries = pageEntries($entries, $page, $perPage);.
Тепер у
functions.phpвісім функцій і жодного виклику чиecho, а блок PHP вindex.php— лише вхідні дані, підключення й виклики. -
Шаблони шапки й підвалу. Виріжте з
index.phpрядки від<!DOCTYPE html>до<main>включно й вставте без змін уsrc/guestbook/templates/header.php. Рядки від</main>до</html>так само перенесіть уfooter.php. Вindex.php:- наприкінці блоку PHP, перед
?>, — коментар// Шапка: від <!DOCTYPE html> до <main>; шаблон бачить змінні сторінки, зокрема $greetingі рядокrequire __DIR__ . '/../../guestbook/templates/header.php';; - останнім рядком файлу, після
</form>, —<?php require __DIR__ . '/../../guestbook/templates/footer.php'; ?>, з початку рядка, без відступу: пробіли перед<?phpпотрапили б у HTML.
Шапка виводить
<?= $greeting ?>, і шаблон бачить цю змінну, бо підключений файл виконується в області видимості рядка зrequire. Тому$greetingобчислюється вище заrequire. Шаблони нічого не оголошують, тож їм доситьrequire, аrequire_onceлишається для файлу з функціями. - наприкінці блоку PHP, перед
-
Перевірка: сторінка та сама. Збережіть ті самі дві сторінки після рефакторингу й порівняйте з кроком 3:
curl -s "http://localhost:8080/guestbook/?hour=20" -o ../step4-hour20.html curl -s "http://localhost:8080/guestbook/?page=2&hour=20" -o ../step4-page2.html git diff --no-index ../step3-hour20.html ../step4-hour20.html git diff --no-index ../step3-page2.html ../step4-page2.htmlgit diff --no-indexпорівнює будь-які два файли, і порожній вивід означає, що HTML збігається символ у символ. Якщо різниця є, найчастіше винні пробіли перед<?php require … footer.php'; ?>, рядок, що загубився чи повторився на межі шаблону, порожній рядок на початкуheader.phpабо перенос рядка, якого бракує після<main>у кінціheader.php.?page=0,?page=99і?page=abcпоказують крайні сторінки, як у кроці 3, безWarning.- Тимчасово додайте під
$entries = require …;рядок$entries = [];: сторінка має показати «Записів ще немає» — без записів, без навігації і безFatal error. Потім видаліть цей рядок. - Відкрийте
http://localhost:8080/guestbook/functions.phpі виконайтеcurl -Iцієї адреси: nginx відповідає404 Not Found, бо вsrc/public/такого файлу немає, аsrc/guestbook/з браузера не дістати.
-
Спершу прогноз, потім запуск. Колега пише окрему сторінку-перегляд оцінки. Для
?rating=4вона мала показати★★★★☆ Оцінка: 4 — Добре, беручиstars()іratingLabel()з гостьової книги, але в коді три помилки. Створіть тренувальний файлsrc/public/bugs-functions.php— не в папціguestbook: це вправа, а не частина книги. Код дослівно (рядок 5 —require, рядок 18 —echo):<?php declare(strict_types=1); // Функції гостьової книги: stars(), ratingLabel() require 'functions.php'; /** * Підпис оцінки для картки запису: «Оцінка: 4 — Добре». */ function ratingCaption($rating) { $caption = "Оцінка: " . $rating . " — " . ratingLabel($rating); } // Оцінка з адресного рядка (?rating=5), за замовчуванням 4 $rating = $_GET['rating'] ?? 4; echo "<p>", stars($rating), " ", ratingCaption($rating), "</p>\n";PHP зупиняється на першій помилці, тож сторінку доведеться запускати кілька разів:
- перед кожним запуском допишіть у кінці файлу коментар-прогноз —
// прогноз 1: …, потім// прогноз 2: …і// прогноз 3: …: що покажеhttp://localhost:8080/bugs-functions.php?rating=4. У кінці файлу коментарі не зсувають номери рядків у повідомленнях PHP; - після запуску біля прогнозу допишіть
// вгадавабо// не вгадав: чому …, як у практиці кроку 3; - виправте помилку, на яку вказує сторінка, — як радять лекції модуля: шлях від
__DIR__,(int)для даних з адреси,return; - виправляючи третю, спершу допишіть
ratingCaption()типи —(int $rating): string— і запустіть ще раз: тепер забутийreturnPHP мовчки не пропустить. Лише потім допишітьreturn.
Наприкінці код сторінки має збігтися з «Очікуваним результатом».
- перед кожним запуском допишіть у кінці файлу коментар-прогноз —
-
Зробіть коміт:
git add src/guestbook src/public/guestbook src/public/bugs-functions.phpіgit commit -m "practice: guestbook functions, data file and templates".
Порада
Документація PHP: власні функції, типи параметрів і результату, require_once, магічні константи, зокрема __DIR__.
Важливо
У index.php і functions.php — лише строгі порівняння: ===, !==, <, <=, >, >=. declare(strict_types=1); — другим рядком кожного з цих двох файлів, одразу після <?php.
Очікуваний результат
Сторінка http://localhost:8080/guestbook/?hour=20 — та сама, що після кроку 3, з вечірнім привітанням:
Сторінки для адрес із кроків 1 і 10 — такі самі, як у кроці 3 (жирним — поточна сторінка, вона без посилання):
| Адреса | Записи на сторінці | Навігація |
|---|---|---|
/guestbook/?hour=20 |
Софія, Богдан, Ірина, Тарас, Марія | 1 2 |
/guestbook/?page=2&hour=20 |
Андрій, Олена | 1 2 |
/guestbook/?page=0 |
Софія, Богдан, Ірина, Тарас, Марія | 1 2 |
/guestbook/?page=99 |
Андрій, Олена | 1 2 |
/guestbook/?page=abc |
Софія, Богдан, Ірина, Тарас, Марія | 1 2 |
-
Обидві команди
git diff --no-indexз кроку 10 нічого не виводять. -
На кожній адресі над записами — «7 записів, середня оцінка 3,9»; з тимчасовим
$entries = [];— лише «Записів ще немає» і форма. -
На жодній із цих сторінок немає
Warning,NoticeчиFatal error. -
Перший рядок відповіді на
curl -I http://localhost:8080/guestbook/functions.php:HTTP/1.1 404 Not Found
Сторінка bugs-functions.php?rating=4, перший запуск — звірте з прогнозом 1:
Warning: require(functions.php): Failed to open stream: No such file or directory in /var/www/html/public/bugs-functions.php on line 5
Fatal error: Uncaught Error: Failed opening required 'functions.php' (include_path='.:/usr/local/lib/php') in /var/www/html/public/bugs-functions.php:5
Stack trace:
#0 {main}
thrown in /var/www/html/public/bugs-functions.php on line 5
Другий запуск, після виправлення шляху. Номер 72 — рядок, де у вашому functions.php оголошено stars(), тож у вас він може бути іншим:
Fatal error: Uncaught TypeError: stars(): Argument #1 ($rating) must be of type int, string given, called in /var/www/html/public/bugs-functions.php on line 18 and defined in /var/www/html/guestbook/functions.php:72
Stack trace:
#0 /var/www/html/public/bugs-functions.php(18): stars('4')
#1 {main}
thrown in /var/www/html/guestbook/functions.php on line 72
Третій запуск, після виправлення типу: жодного повідомлення, але код сторінки (Ctrl+U) — <p>★★★★☆ </p>: підпис оцінки порожній. Після того як ви дописали ratingCaption() типи з кроку 11, але ще без return, сторінка показує:
★★★★☆
Fatal error: Uncaught TypeError: ratingCaption(): Return value must be of type string, none returned in /var/www/html/public/bugs-functions.php:13
Stack trace:
#0 /var/www/html/public/bugs-functions.php(18): ratingCaption(4)
#1 {main}
thrown in /var/www/html/public/bugs-functions.php on line 13
Код сторінки після всіх виправлень (Ctrl+U):
<p>★★★★☆ Оцінка: 4 — Добре</p>
Критерії оцінювання
Роботу оцінюють за 10-бальною шкалою:
| Критерій | Бали |
|---|---|
Сторінка не змінилася: обидва git diff --no-index з кроку 10 нічого не виводять; ?page=0, ?page=99, ?page=abc і порожня книга — як у кроці 3, без попереджень; /guestbook/functions.php — 404 |
2 |
src/guestbook/functions.php (кроки 4–8): declare(strict_types=1), вісім функцій з типами параметрів і результату та doc-коментарем; кожна повертає значення через return і нічого не виводить; index.php і шаблон викликають їх замість старих блоків; лише строгі порівняння |
3 |
Файли поза веб-коренем (кроки 2, 3, 9): записи в data.php з return [...], шапка й підвал у templates/, require_once для функцій і require для даних і шаблонів, шляхи від __DIR__; declare(strict_types=1) в index.php |
2 |
bugs-functions.php (крок 11): прогноз до кожного запуску, позначки вгадав / не вгадав: чому, три виправлення, код сторінки як в «Очікуваному результаті» |
2 |
Коміт practice: guestbook functions, data file and templates |
1 |
| Разом | 10 |
Завдання з розділу «Додатково (*)» балів понад 10 не додає: воно може повернути до 2 балів, знятих за критеріями вище, але оцінка не перевищує 10.
Що здати
Посилання на коміт practice: guestbook functions, data file and templates з такими файлами:
src/guestbook/functions.php,src/guestbook/data.php;src/guestbook/templates/header.php,src/guestbook/templates/footer.php;src/public/guestbook/index.php,src/public/bugs-functions.php.
Або архів, якщо так домовлено на занятті. Будьте готові пояснити, що повернуть pluralEntries(112) і pageEntries($entries, 2, 5) і чому браузер не відкриває functions.php.
Додатково (*)
-
Функції без браузера. Функцію можна перевірити окремо від сторінки — з терміналу, у контейнері
php, де робочий каталог/var/www/html, тобтоsrc/:docker compose exec php php -r "require 'guestbook/functions.php'; echo pluralEntries(112), PHP_EOL;"Перевірте так
pluralEntries()для 0, 1, 3, 11, 21 і 112 таgreeting()для 4, 5, 12, 18 і 23 і звірте результати з вимогами практики «Гостьова книга, крок 1: сторінка, що ухвалює рішення». Так починаються автоматичні тести. -
Друга сторінка з тими самими шаблонами. Додайте шапці змінну
$title(у<title>і<h1>) і створітьsrc/public/guestbook/about.php— «Про гостьову книгу»: кілька речень і посилання на/guestbook/, з тими самимиheader.phpіfooter.php. Що ще має задати нова сторінка, щоб шапка не показалаWarning? Головна сторінка має лишитися без змін — перевірте це черезgit diff --no-index. -
Розподіл оцінок функцією. Напишіть
ratingCounts(array $entries): array— масив із ключами-оцінками від 5 до 1 і кількістю записів із кожною — і покажіть розподіл під підписом кількості.