Перейти до змісту
Intita
Практика · 45 хв · Макс. бал: 10

Гостьова книга, крок 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: код у кількох файлах».

Кроки

  1. Знімок «до». Запустіть робочий проєкт 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.

  2. Папки поза веб-коренем. Створіть папку src/guestbook/, а в ній — templates/: поруч із src/public/, а не всередині. Корінь сайту для nginx — src/public/, і файл поза ним браузер не відкриє: так було з src/test.php у практиці «Практика: розгортаємо середовище PHP-розробника». А PHP підключає файли звідки завгодно. У контейнері php папка src/ — це /var/www/html.

  3. Записи — у 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.

    Оновіть сторінку: записи на місці.

  4. Файл функцій і строгий режим. Створіть 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 уже робить із них числа, тож строгий режим сторінку не зламає.
  5. Перша функція: 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-коментар /** … */ з одним реченням про те, що вона повертає, і тип кожного параметра й результату.
  6. Оцінка запису: 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 більше немає: функції не змінюють масив, а повертають значення.

  7. Підпис кількості: 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 записів.
  8. Середня й сторінки.

    • 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 — лише вхідні дані, підключення й виклики.

  9. Шаблони шапки й підвалу. Виріжте з 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 лишається для файлу з функціями.

  10. Перевірка: сторінка та сама. Збережіть ті самі дві сторінки після рефакторингу й порівняйте з кроком 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.html
    

    git 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/ з браузера не дістати.
  11. Спершу прогноз, потім запуск. Колега пише окрему сторінку-перегляд оцінки. Для ?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 — і запустіть ще раз: тепер забутий return PHP мовчки не пропустить. Лише потім допишіть return.

    Наприкінці код сторінки має збігтися з «Очікуваним результатом».

  12. Зробіть коміт: git add src/guestbook src/public/guestbook src/public/bugs-functions.php і git commit -m "practice: guestbook functions, data file and templates".

Важливо

У 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.

Додатково (*)

  1. Функції без браузера. Функцію можна перевірити окремо від сторінки — з терміналу, у контейнері 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: сторінка, що ухвалює рішення». Так починаються автоматичні тести.

  2. Друга сторінка з тими самими шаблонами. Додайте шапці змінну $title (у <title> і <h1>) і створіть src/public/guestbook/about.php — «Про гостьову книгу»: кілька речень і посилання на /guestbook/, з тими самими header.php і footer.php. Що ще має задати нова сторінка, щоб шапка не показала Warning? Головна сторінка має лишитися без змін — перевірте це через git diff --no-index.

  3. Розподіл оцінок функцією. Напишіть ratingCounts(array $entries): array — масив із ключами-оцінками від 5 до 1 і кількістю записів із кожною — і покажіть розподіл під підписом кількості.