Update tutorial.xml to en

2026-03-23 23:32:16 +01:00 · 2026-01-12 09:14:49 +03:00
parent 8f23a27843
commit 392573e37d
1 changed files with 83 additions and 130 deletions
--- a/chapters/tutorial.xml
+++ b/chapters/tutorial.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 1fd637525fd3bbaec04f6fff80eeb33fce880b10 Maintainer: shein Status: ready -->
+<!-- EN-Revision: 876557ae38f6ca5035618f7cea48ca627118b437 Maintainer: shein Status: ready -->
 <!-- Reviewed: no -->
 <chapter xml:id="tutorial" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <info><title>Простой учебник</title></info>
@@ -8,59 +8,25 @@
   Это краткое и простое руководство показывает только основы PHP.
   Текст рассказывает, только как создавать динамические
   веб-страницы на PHP, хотя PHP умеет больше.
-   Раздел «<link linkend="intro-whatcando">Что умеет
-   PHP</link>» даёт дополнительную информацию.
+   Раздел «<link linkend="intro-whatcando">Что умеет PHP</link>»
+   даёт дополнительную информацию.
  </para>
  <para>
-   Веб-страницы с поддержкой PHP обрабатываются так же, как обычные
-   HTML-страницы, их создают и редактируют так же,
-   как обычные страницы на языке HTML-разметки.
+   Веб-страницы с поддержкой PHP обрабатываются аналогично
+   HTML-страницам: PHP-страницы создают и редактируют аналогично
+   страницам на языке HTML-разметки.
  </para>

-  <section xml:id="tutorial.requirements">
-   <info><title>Что мне потребуется?</title></info>
-   <para>
-    Руководство предполагает, что на сервере уже активировали
-    поддержку PHP, и что файлы, имена которых заканчиваются на <filename class="extension">.php</filename>,
-    обрабатывает PHP. На большей части серверов PHP-файлы обрабатывает модуль по умолчанию
-    для PHP-файлов, но всё равно лучше попросить администратора сервера
-    проверить это. Итак, если сервер поддерживает PHP, то ничего делать
-    не нужно. Просто создавайте файлы <filename class="extension">.php</filename>
-    и размещайте их в каталоге веб-сервера — они будут обрабатываться
-    автоматически. Не нужно ничего компилировать или устанавливать
-    дополнительные инструменты. Думайте о PHP-файлах как о простых HTML-файлах
-    с набором новых «волшебных» тегов, которые умеют делать всё, что требуется.
-   </para>
-   <para>
-    Например, требуется сэкономить на интернет-канале и вести разработку локально.
-    Тогда потребуется установить веб-сервер наподобие <link
-    xlink:href="&url.apache;">Apache</link>, и, разумеется, <link
-    xlink:href="&url.php.downloads;">PHP</link>. Скорее всего, потребуется
-    установить базу данных, например, <link xlink:href="&url.mysql.docs;">MySQL</link>.
-   </para>
-   <para>
-    Всё это устанавливают по-отдельности или поступают проще:
-    руководство приводит <link linkend="install">инструкции по установке PHP</link>
-    (предполагается, что веб-сервер уже установили). Если при установке PHP
-    возникли проблемы, задайте вопросы через
-    <link xlink:href="&url.php.mailing-lists;">список рассылки по вопросам
-    установки</link>. Если же выбрали более простой способ,
-    <link xlink:href="&url.installkits;">найдите уже настроенный пакет</link>
-    для своей операционной системы, который автоматически установит всё
-    перечисленное за несколько щелчков мыши. Веб-сервер с поддержкой PHP
-    легко настроить в любой операционной системе, включая Mac OS X, Linux и Windows.
-    На Linux для поиска RPM-пакетов, возможно, пригодятся страницы
-    <link xlink:href="&url.rpmfind;">rpmfind</link> и <link xlink:href="&url.rpmfind.pbone;">PBone</link>.
-    Страница <link xlink:href="&url.apt-get;">apt-get</link>
-    помогает в поиске пакетов для ОС Debian.
-   </para>
-  </section>
-
  <section xml:id="tutorial.firstpage">
   <info><title>Первая страница на PHP</title></info>
+   <simpara>
+    Вначале потребуется установить PHP.
+    Инструкция по установке доступна
+    <link xlink:href="&url.php.downloads;">на странице загрузки</link>.
+   </simpara>
   <para>
-    Создайте файл с именем <filename>hello.php</filename> в корневом каталоге веб-сервера
-    (<varname>DOCUMENT_ROOT</varname>) и запишите в него следующее:
+    Теперь создадим файл с названием <filename>hello.php</filename>
+    и напишем внутри следующий код:
   </para>
   <para>
    <example>
@@ -69,22 +35,29 @@
 <![CDATA[
 <?php

-echo "Hello World!";
-
-?>
+echo "Привет, мир!";
 ]]>
     </programlisting>
     <simpara>
-      Запустите браузер для доступа к файлу на веб-сервере по URL-адресу, который заканчивается
-      ссылкой на файл <literal>/hello.php</literal>. При локальной разработке
-      URL-адрес будет выглядеть примерно как <literal>http://localhost/hello.php</literal>
-      или <literal>http://127.0.0.1/hello.php</literal> в зависимости от конфигурации
-      веб-сервера. При корректной конфигурации веб-сервера PHP
-      разберёт файл, а браузер выведет приветствие «Привет, мир!».
+      В терминале перейдём в каталог, в котором содержится файл,
+      и запустим сервер разработки следующей командой:
+     </simpara>
+     <programlisting role="shell">
+<![CDATA[
+php -S localhost:8000
+]]>
+     </programlisting>
+     <simpara>
+      Для доступа к файлу в браузере указывают URL-адрес,
+      который состоит из адреса веб-сервера и ссылки на файл: <literal>/hello.php</literal>.
+      Из команды, которую выполнили на предыдущем шаге, возьмём адрес веб-сервера и построим полный URL-адрес:
+      <literal>http://localhost:8000/hello.php</literal>.
+      При правильной конфигурации PHP обработает файл,
+      а браузер покажет вывод: "Привет, мир!".
     </simpara>
     <simpara>
-      PHP-код разрешают встраивать внутрь HTML-разметки веб-страницы. Поэтому PHP-инструкции
-      записывают внутри HTML-документа, как показывает следующий пример:
+      PHP-интерпретатор умеет генерировать веб-страницы из исходного кода, в котором PHP-код встроили в HTML-разметку.
+      Поэтому PHP-инструкции записывают непосредственно внутри разметки будущего HTML-документа, как показывает следующий пример:
     </simpara>
     <programlisting role="php">
 <![CDATA[
@@ -119,35 +92,23 @@ echo "Hello World!";
   </para>
   <para>
    Эта программа чрезвычайно проста, и чтобы создать настолько простую
-    страницу, даже не обязательно запускать и писать код на PHP. Всё, что делает программа, —
-    выводит строку <literal>Hello World</literal> через PHP-инструкцию
-    <function>echo</function>. Заметьте, что файл <emphasis>не обязан быть
-    исполняемым</emphasis> или ещё каким-то образом отличаться от других файлов.
+    страницу, даже не обязательно запускать и писать код на PHP. Единственное, что делает программа, —
+    выводит строку <literal>Привет, мир!</literal> PHP-инструкцией
+    <function>echo</function>. Заметьте, что файл <emphasis>не требуется делать исполняемым</emphasis>
+    или ещё каким-то образом отличаться от других файлов.
    Сервер знает, что этот файл требуется интерпретировать средствами PHP, поскольку
-    расширение файла — «.php», которое сервер настроен передавать PHP.
+    расширение файла — ".php", которое сервер настроен передавать PHP.
    О PHP-файле думают как об обычном HTML-файле,
    который содержит набор тегов, которые умеют делать много интересного.
   </para>
+
   <para>
-    Если пример ничего не вывел, появилось окно загрузки файла
-    или код отображается как обычный текст, скорее всего,
-    на веб-сервере не включили PHP или неправильно сконфигурировали сервер.
-    Попросите администратора сервера включить такую поддержку.
-    Предложите администратору инструкцию по установке: раздел «<link linkend="install">Установка и настройка</link>».
-    Если разработка ведётся локально,
-    также прочтите главу об установке, чтобы точно знать, что всё настроили правильно.
-    Убедитесь также, что файл запрашивается с сервера, который отдаёт данные вывода, через HTTP-протокол.
-    Если просто обратиться к файлу из файловой системы, PHP не будет его обрабатывать.
-    Обращайтесь к <link xlink:href="&url.php.support;">способам поддержи</link> PHP-программистов,
-    если ошибки всё равно остаются.
-   </para>
-   <para>
-    Цель примера — показать формат PHP-тегов. В примере
-    мы указали <literal>&lt;?php</literal>, чтобы обозначить начало
-    PHP-тега. Затем мы поместили PHP-инструкцию и вышли из режима PHP,
-    добавив завершающий тег <literal>?&gt;</literal>. Так можно входить
-    и выходить из режима PHP в произвольном месте HTML-файла. Подробнее об этом рассказывает
-    раздел руководства «<link linkend="language.basic-syntax">Основы синтаксиса</link>».
+    Цель примера — показать формат PHP-тегов. Тег <literal>&lt;?php</literal> обозначает начало
+    PHP-кода. Затем идёт PHP-инструкция и тег <literal>?&gt;</literal>,
+    который заставляет парсер выйти из режима интерпретации PHP-кода.
+    Теги указывают в произвольном месте файла, когда требуется переключить режимы интерпретации PHP-кода и анализа HTML-разметки.
+    Подробнее о разборе исходного кода рассказывает раздел руководства
+    «<link linkend="language.basic-syntax">Основы синтаксиса</link>».
   </para>

   <note>
@@ -181,30 +142,28 @@ echo "Hello World!";
    <info><title>Кратко о текстовых процессорах</title></info>
    <para>
     В текстовых процессорах наподобие StarOffice Writer, Microsoft Word и Abiword
-     неудобно редактировать PHP-файлы. Убедитесь, что сохраняете файл как
-     <emphasis>простой текст</emphasis> (plain text), если редактируете тестовый скрипт
-     в каком-то из них, иначе PHP не сумеет прочитать и запустить скрипт.
+     неудобно редактировать PHP-файлы. Убедитесь, что сохраняете файл
+     в формате <emphasis>plain text</emphasis>, если изменяете тестовый скрипт
+     в таком редакторе, иначе не получится прочитать и выполнить PHP-скрипт.
    </para>
   </note>

   <para>
-    Теперь, когда работающий PHP-скрипт успешно создали, самое время создать самый
+    Теперь, когда узнали основы языка, пора создать самый
    знаменитый PHP-скрипт! Вызовите функцию <function>phpinfo</function> и увидите
    много полезной информации о системе и настройке, например, доступные
    <link linkend="language.variables.predefined">предопределённые переменные</link>,
    загруженные PHP-модули и <link linkend="configuration">параметры настройки</link>.
-    Уделите некоторое время изучению этой важной информации.
+    Уделите время изучению этой важной информации.
   </para>
   <para>
    <example>
-     <info><title>Получение информации о системе из PHP</title></info>
+     <info><title>Получение информации о системе средствами PHP</title></info>
     <programlisting role="php">
 <![CDATA[
 <?php

 phpinfo();
-
-?>
 ]]>
     </programlisting>
    </example>
@@ -212,36 +171,35 @@ phpinfo();
  </section>

  <section xml:id="tutorial.useful">
-   <info><title>Делаем что-нибудь полезное</title></info>
+   <info><title>Примеры кода</title></info>
   <para>
-    Давайте сделаем что-нибудь полезное. Например, узнаем, каким браузером пользуется
-    клиент, который просматривает нашу страницу. Для этого проверим строку пользовательского
-    агента, которую браузер отправляет как часть HTTP-запроса. Эта информация хранится в <link
-    linkend="language.variables">переменной</link>. Переменные в PHP
-    предваряются знаком доллара. Переменная, которая нас интересует,
-    называется <varname>$_SERVER['HTTP_USER_AGENT']</varname>.
+    Теперь напишем полезный код и узнаем, в каком браузере
+    посетитель просматривает страницу. Для этого проверим строку пользовательского
+    агента, которую браузер отправляет как часть HTTP-запроса. Информация об агенте содержится
+    в массиве, который хранится <link linkend="language.variables">в переменной</link>.
+    В PHP каждая переменная начинается со знака доллара, а значение отдельного элемента массива
+    в переменной получают по ключу. Извлечём строку пользовательского агента из элемента
+    <varname>$_SERVER['HTTP_USER_AGENT']</varname>.
   </para>
   <note>
    <para>
-     Переменная <varname>$_SERVER</varname> — зарезервированная PHP-переменная,
-     которая содержит информацию, которую PHP получил от веб-сервера. Переменную также называют
-     суперглобальной. Дополнительную информацию смотрите в разделе «<link
-     linkend="language.variables.superglobals">Суперглобальные переменные</link>».
+     <varname>$_SERVER</varname> — суперглобальная зарезервированная переменная,
+     которую PHP заполняет информацией о запросе, среде выполнения и серверном окружении.
+     Дополнительную информацию о таких переменных содержит раздел
+     «<link linkend="language.variables.superglobals">Суперглобальные переменные</link>».
    </para>
   </note>
   <para>
-    Для вывода переменной мы сделаем так:
+    Для вывода значения элемента массива, который хранится в переменной, напишем следующий код:
   </para>
   <para>
    <example>
-     <info><title>Вывод значения переменной (элемента массива)</title></info>
+     <info><title>Вывод значения элемента массива</title></info>
    <programlisting role="php">
 <![CDATA[
 <?php

 echo $_SERVER['HTTP_USER_AGENT'];
-
-?>
 ]]>
    </programlisting>
    <para>
@@ -255,14 +213,13 @@ Mozilla/5.0 (Linux) Firefox/112.0
   </example>
   </para>
   <para>
-    В PHP доступен ряд <link linkend="language.types">типов</link>
-    переменных. В предыдущем примере мы выводили на печать элемент
-    <link linkend="language.types.array">массива</link>. Массивы
-    бывают полезны.
+    В PHP-переменных хранят числа, строки, массивы и значения других <link linkend="language.types">типов</link>.
+    Тип значения, элемент которого выводил код предыдущего примера, называется <link linkend="language.types.array">массивом</link>.
+    Массивы полезны для хранения значений произвольных типов.
   </para>
   <para>
-    Переменная <varname>$_SERVER</varname> — только одна переменная, которую
-    PHP автоматически делает доступной. Список таких переменных приводит раздел
+    Переменная <varname>$_SERVER</varname> — только один пример переменной,
+    к которой PHP автоматически открывает доступ. Список таких переменных приводит раздел
    «<link linkend="reserved.variables">Зарезервированные переменные</link>»
    или вывод функции <function>phpinfo</function>, которую приводил
    как пример предыдущий раздел.
@@ -284,8 +241,6 @@ Mozilla/5.0 (Linux) Firefox/112.0
 if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
    echo 'Вы пользуетесь браузером Firefox.';
 }
-
-?>
 ]]>
     </programlisting>
     <para>
@@ -328,7 +283,7 @@ if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
   </para>
   <para>
    Пойдем дальше и покажем, как переходить в режим PHP и выходить
-    из него даже в середине блока PHP-кода:
+    из режима интерпретации даже в середине блока PHP-кода:
   </para>
   <para>
    <example>
@@ -339,17 +294,15 @@ if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {

 if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
 ?>
-    <h3>Функция str_contains() возвращает true</h3>
-    <p>Вы пользуетесь браузером Firefox.</p>
+    <h3>Функция str_contains() вернула значение true</h3>
+    <p>Вы просматриваете страницу в браузере Firefox.</p>
 <?php
 } else {
 ?>
-    <h3>Функция str_contains() возвращает false</h3>
-    <p>Вы не пользуетесь браузером Firefox.</p>
+    <h3>Функция str_contains() вернула значение false</h3>
+    <p>Ваш браузер не похож на Firefox.</p>
 <?php
 }
-
-?>
 ]]>
     </programlisting>
     <para>
@@ -357,19 +310,19 @@ if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
     </para>
     <screen role="html">
 <![CDATA[
-<h3>Функция str_contains() возвращает true</h3>
-<p>Вы пользуетесь браузером Firefox.</p>
+<h3>Функция str_contains() вернула значение true</h3>
+<p>Вы просматриваете страницу в браузере Firefox.</p>
 ]]>
     </screen>
    </example>
   </para>
   <para>
-    Вместо вызова PHP-инструкции echo для вывода текста, мы вышли из режима
-    PHP и просто отправили HTML-код. Важный момент здесь состоит в том, что логическая
-    структура PHP-кода остается неизменной. Только один HTML-блок будет
-    отправлен клиенту в зависимости от результата функции
-    <function>str_contains</function>. Другими словами, поведение завист от того,
-    нашла ли функция строку <literal>«Firefox»</literal> или нет.
+    Вместо вывода текста инструкцией echo, мы вышли из режима
+    интерпретации PHP-кода и написали HTML-разметку.
+    Логическая последовательность выполнения PHP-кода при этом сохраняется:
+    PHP отправит пользователю только один блок HTML-разметки
+    на основе значения, которое вернёт функция <function>str_contains</function>
+    по результатам поиска подстроки <literal>Firefox</literal>.
   </para>
  </section>

@@ -378,8 +331,8 @@ if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
   <para>
    Список преимуществ PHP дополняет способ обработки HTML-форм.
    Основа заключается в том, что PHP-скрипт автоматически получает доступ к каждому элементу формы.
-    Подробнее о работе с формами в PHP рассказывает раздел «<link linkend="language.variables.external">
-    Переменные из внешних источников</link>». Вот пример HTML-формы:
+    Подробнее о работе с формами в PHP рассказывает раздел
+    «<link linkend="language.variables.external">Переменные из внешних источников</link>». Вот пример HTML-формы:
   </para>
   <para>
    <example>