Пояснения предназначены в первую очередь для программистов, которые собираются изменять MyRewriter. Но и просто пользователям будет полезно почитать.
Это костяк документации, ещё не до конца наполненный содержимым. Впоследствии почти вся новая техническая информация по MyRewriter'у будет добавляться именно сюда.



Папка functions. Файлы с функциями, используемыми скриптом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта. Стараемся придерживаться правила: "одна функция - один файл". Имя функции совпадает с названием файла, если для разделения слов вместо нижнего подчёркивания использовать заглавные буквы. Например, в файле my_cool_function.php должна быть функция MyCoolFunction().

Файл add_synonyms_to_database.php. Получает текст в формате
крокодил|аллигатор
аллигатор|крокодил
красивые цветы|цветочки

и добавляет его в базу. Если фраза (левая часть) уже есть в базе, то она не добавляется. Выводит статистику: сколько слов было, сколько и каких добавили, сколько и каких не добавили.

Файл begin_html.php. Выводит в броузер шапку из HTML-тегов. К html подключается файл style.css текущего шаблона.

Файл check_host.php. Вызывается при каждом запуске скрипта, останавливает работу, если обнаруживает, что настройки хоста не подходят.

Файл connect_to_database.php. Подключается к базе данных (настройки берутся из service/config.php), проверяет, есть ли в базе хоть что-то. Если нет и это не установка (нет константы IT_IS_INSTALLATION), то выводится ошибка и работа скрипта прерывается.

Файл count_all_synonyms.php. Подсчитывает общее число синонимов в базе.

Файл delete_all_synonyms.php. Удаляет из базы все синонимы.

Файл delete_blank_lines.php. Получает текст и удаляет из него все пустые строки. Используется при добавлении синонимов в базу.

Файл delete_comments.php. Удаляет из текста комментарии (всё от "#" или "//" до конца строки). Используется при добавлении синонимов в базу. Синонимы удобно до добавления хранить в текстовом файле, а в нём иногда полезно ставить комментарии. MyRewriter не споткнётся на них.

Файл delete_too_long_lines.php. Принимает строки в формате
крокодил|аллигатор
аллигатор|крокодил
красивые цветы|цветочки

и удаляет те, где либо фраза либо синоним длиннее 255 символов. Это лучше, чем случай, когда они записываются в базу не целиком. При этом об отброшенных строках выводятся сообщения типа info.

Файл end_html.php. Просто выводит </body> и </html>

Файл first_letter_of_each_sentence_to_upper.php. При синонимизации слова, написанные с большой буквы, заменяются на синонимы с маленькой. Функция пытается исправить эту проблему - делает первую букву слова в начале предложения заглавной. Находит первые слова предложений и передаёт их в FirstLetterOfStringToUpper() (см. ниже).

Файл first_letter_of_string_to_upper.php. Эта функция используется предыдущей. Принимает строку и делает её первую букву заглавной.

Файл is_debug_mode.php. Проверяет, передан ли в урле параметр d == 1. Например http://localhost/index.php?d=1. Используется в service/some_service_work_after_functions.php, чтобы проверить, нужно ли включать режим отладки.

Файл prepare_synonyms_and_add_them.php. Подготавливает синонимы к добавлению в базу (удаляет пустые строки, комментарии...) и добавляет их (передаёт в AddSynonymsToDatabase()).

Файл prepare_text_and_synonymize_it.php. Подготавливает текст к синонимизации (заменяет ё на е, конвертирует переводы строк в unix-style...) и передаёт его в SynonymizeText().

Файл show_synonyms_adding_form.php. Выводит форму для добавления новых синонимов. Отправка по Ctrl + Enter.

Файл start_counter.php. Запускает счётчик - возвращает текущее время с микросекундами как строку. Вызывается обычно как
$GLOBALS["CounterStartTime"] = StartCounter();

Файл stop_counter.php. Возвращает разницу между полученным временем и текущим. Стандартно используется как
WriteMessage("Время работы кода в счётчике", StopCounter($GLOBALS["CounterStartTime"]), "info");

Файл stripslashes_for_array.php. Принимает массив, рекурсивно обходит его и применяет stripslashes() ко всем элементам. Используется в самом начале, в service/some_service_work_after_functions.php, чтобы очистить от слешей $_GET, $_POST, $_COOKIE и $_REQUEST, если включена magic_quotes_gpc.

Файл synonymize_phrase.php. Получает слово и синоним. Собирает некоторую статистику, возвращает синоним. Если включена SHOW_TIPS, то с всплывающей подсказкой, где текст подсказки - бывшее слово.

Файл synonymize_text.php. Синонимизирует полученный текст.

Файл write_message.php. Выводит сообщение. В зависимости типа отображает его по-разному и может выполнять какие-то специальные действия. Например, если тип error, то отправляет письмо-уведомление на админский ящик (если разрешено) и заканчивает работу скрипта.



Папка interfaces. Интерфейсы - удобная фишечка MyRewriter'а. Если говорить грубо, есть ядро - функции, занимающиеся синонимизированием, а есть интерфейсы - скрипты, занимающиеся передачей текстов в ядро. И это сильно упрощает жизнь тем, кто хочет получать/отправлять данные нестандартным способом.

Поясню на примере. Вот код файла start_synonymization.php интерфейса standart_browser. Синонимизированный текст вводится в форму в броузере, выводится тоже прямо в броузер.

(Заезжает под правую колонку, знаю. Ну и ладно. Тем, кто не сможет скопировать, код явно не нужен :-) )

<?php
/*
MyRewriter 1.2
http://shop.all4wm.net/myrewriter/
*/

//Если через POST передан текст, то синонимизирует его, иначе показывает форму для ввода текста.
function StartSynonymization ()
{
   //Если форма не отправлена, то не надо ничего синонимизировать. Покажем форму
   if (!isset($_POST["text"]))
   {
      ShowTextSynonymizingForm();
      return;
   }
   
   //Если форма отправлена
   
   $CurrentContent = $_POST["text"];
   WriteMessage("Необработанный текст, который передали в форму:", $CurrentContent, "debug");
   
   //Синонимизируем и выводим прямо в броузер, заменяя переводы строк на <br />.
   $CurrentContent = PrepareTextAndSynonymizeIt($CurrentContent);
   echo nl2br($CurrentContent);
   
   WriteMessage("Всё синонимизировалось", "<a href='".VIRTUAL_PATH."'>Ещё &gt;</a>", "imp_info");
}
?>
Большая часть - мишура и комментарии, три важные строки я подсветил красным. Первая - получаем текст. Вторая - синонимизируем. Третья - отдаём пользователю. Очень просто. Достаточно заменить echo() на mail(), чтобы получить новый интерфейс, который отправляет синонимизированные тексты на почту. Интеграция с твоим скриптом, получающим откуда-нибудь текст, займёт совсем немного времени. Конечно, может понадобиться ещё поправить функции сбора/показа статистики, но это легко и необязательно.

Чтобы выбрать для работы какой-то интерфейс, имя его папки нужно написать в файле service/config.php в константу CURRENT_INTERFACE.

Папка standart_browser. Стандартный интерфейс, который принимает тексты, переданные через броузер (введённые в текстовое поле) и отдаёт синонимизированные тоже прямо в броузер.

Папка functions. Файлы с функциями, используемыми интерфейсом. Все .php файлы, положенные в неё, автоматически подключаются при работе скрипта, если выбран этот интерфейс.

Файл gather_stats.php. Собирает статистику и записывает её в базу. Всегда вызывается при добавлении синонимов в базу (это достаточно редкая операция и можно позволить себе потратить время на сбор статистики) и собственно при работе скрипта, если включена опция STATS_ONLINE_GATHERING. Если статистика не нужна, можно её выключить и чуть-чуть уменьшить время работы. Своя собственная у каждого интерфейса.

Файл show_synonymizing_stats.php. Показывает статистику синонимизации. Не собирает статистику, но просто берёт значения из базы. Разделение сбора-отображения на две функции даёт определённую дополнительную гибкость.

Файл show_text_synonymizing_form.php. Отдаёт в броузер форму для ввода текста, который будет синонимизироваться.

Файл start_synonymization.php. Непосредственно синонимизация. Этот файл свой в каждом интерфейсе, его задача - взять откуда-то текст (в данном случае текст вводят в броузер), передать его в PrepareTextAndSynonymizeIt() и выдать (в этом интерфейсе - прямо в броузер) готовый результат. Вызывается из index.php после подключения всего нужного.

Папка service. Настройки, служебная работа для этого интерфейса. Тут есть несколько пустых файлов - в них было нечего написать. Они не удалены, это позволит избежать путаницы с именами при изменении интерфейса.

Файл config.php. Тут теоретически должны быть настройки интерфейса. Но настроек нету, поэтому файл пустой.

Файл include_all_functions.php. Подключаем все файлы с расширением .php из папки functions этого интерфейса. Подключаются функции не всегда, но только в случае, если интерфейс активен.

Файл prepare_for_work.php. Подготавливает интерфейс к работе - подключает сервисные скрипты, лежащие в этой папке.

Файл some_service_work_after_functions.php. Предназначен для каких-то сервисных действий интерфейса, вызывается после подключения функций. Пустой.

Файл some_service_work_before_functions.php. Аналогично предыдущему, вызывается до функций. Тоже пустой.

Папка standart_files. Стандартный интерфейс, тексты берутся из файлов, в файлы же записываются. Кодировка обязательно должна быть UTF-8.

(этот кусок документации ещё не написан)



Папка service. Место, где живут скрипты, подготавливающие MyRewriter к работе. Там же настройки.

Файл config.php. Все доступные настройки скрипта (у интерфейсов свои настройки) находятся именно здесь.

Файл include_all_functions.php. Подключает все файлы с расширением .php из папки functions.

Файл prepare_for_work.php. Подготавливает MyRewriter к работе, должен подключаться всегда в самом начале. Тут чтение настроек, подключение всего необходимого, запуск счётчика...

Файл some_service_work_after_functions.php. Кое-какие служебные действия, выполняются после подключения всех фукций. Некоторые проверки конфигурации хоста, соединение с БД.

Файл some_service_work_before_functions.php. Тоже сервисная работа, но выполняется до подключения всех функций. Сейчас там установка множества констант с путями до различных частей скрипта - без этого неудобно подключать функции. Причём пути сейчас определяются абсолютно ужасными способами, надо не забыть исправить.



Папка templates. Если тебе придёт в голову изменить оформление MyRewriter'а (правильнее сказать - добавить к MyRewriter'у оформление :-) ), то следует создать в templates папку с именем шаблона и изменить на это имя значение константы CURRENT_TEMPLATE в service/config.php. В каждом шаблоне основной файл стилей должен называться style.css, тогда он будет автоматически подключаться к html-коду.

Папка first. Там живёт единственный идущий в комплекте файл стилей.

Файл style.css. Стили для разных сообщений и для всплывающих подсказок.



Файл .htaccess. Предлагает PHP не использовать Волшебные Кавычки (опция PHP, цель которой - портить кровь программистам) для скриптов этой папки.

Файл add.php. Используется для добавления синонимов в базу (ну и удаления из базы).

Файл check.php. Проверялка конфигурации хоста, используется сама по себе, для работы или установки MyRewriter'а больше не нужна. check.php не проверяет версию PHP - мы ещё не успели тщательно разобраться, что подходит, а что - нет. Но теоретически проблем быть не должно.

Файл index.php. Собственно, при запуске этого скрипта и будет происходить синонимизация.

Файл install.php. Инсталлятор. Создаст нужные таблицы в базе данных, импортирует синонимы из файла syns.txt.

Файл syns.txt. Синонимы. Вручную отобранные 1200 с лишним пар фраза|синоним. Как показывает практика, этого достаточно, чтобы заменять где-то каждое двенадцатое слово без значительной потери читаемости. При желании можно скормить MyRewriter'у какую-то из бесплатных мусорных баз синонимов, но текст будет годен только на дорвеи.