Merge pull request #16 from KarelWintersky/Version_2

Version 2

.gitignore

@@ -1,7 +1,17 @@
-.idea
+# exclude git
 .git
-.localfiles
-sources/config.db.ini
-sources/config.sitemap+db.ini
-tests/make_db_seed.ini
-production/config.sitemap+db.ini
+
+# exclude IDE files
+.idea
+
+# exclude temporary development files
+_todo/*
+
+# exclude build temporary files
+debian/kwsitemapgenerator/*
+
+# exclude environment-depend config
+sources/*.ini
+_temp/*
+production/*.ini
+

README.md

@@ -15,54 +15,67 @@
 
 ## Установка
 
-Все исходники лежат в каталоге `/sources` и собираются в `sitemap_generator.php` при помощи build-скрипта.
+Все исходники лежат в каталоге `/sources` и собираются в `sitemap_generator.php` при помощи make-команды.
 
 ```
-/bin/bash ./build.sitemap_generator.sh
+make build_generator
 ```
 
 Готовый файл можно положить куда-нибудь и запускать без указания пути к интерпретатору:
 ```
-chmod +x ./production/sitemap_generator.php
-mv ./production/sitemap_generator.php /usr/local/bin
+sudo mv ./production/sitemap_generator.php /usr/local/bin/sitemap_generator.php
+sudo chmod +x ./production/sitemap_generator.php
 sitemap_generator.php --help
 ```
 
+или
+```
+make install
+```
+
 ## Запуск
 
 Теперь мы можем запустить его из консоли, передав ему аргументом путь к файлу конфигурации:
 
 ```
-/usr/local/bin/sitemap_generator.php /path/fo/my_sitemap.ini
+/usr/local/bin/sitemap_generator.php --config /path/fo/my_sitemap.ini
 ```
 
 Или, из текущего каталога:
 ```
-/usr/local/bin/sitemap_generator.php my_sitemap.ini
+/usr/local/bin/sitemap_generator.php --config my_sitemap.ini
 ```
 
-## Настройка
+## Параметры командной строки
+
+- `--config` - обязательная опция, требует указания конфига. Без неё выводится справка
+- `--help` - необязательная опция, выводит справку.
+- `--verbose` - необязательная опция, перекрывает опцию конфигурации `logging` из глобальной секции и выводит прогресс постройки sitemaps. 
+
+## Безопасность доступа
 
 Все настройки доступа к БД и инструкции по построению сайтмэпов задаются в ini-файлах. Предполагается, что конфиг-файлы недоступны
 посторонним, но я все равно рекомендую создать для генерации сайтмэпа отдельного пользователя исключительно с правом SELECT
-и использовать в файлах конфигурации эти значения.
+и указывать его credentials в файле конфигурации:
 
 ```
 CREATE USER 'sitemapcreator'@'localhost' IDENTIFIED BY 'sitemappassword';
 GRANT SELECT ON database.* TO `sitemapcreator`@`localhost`;
 FLUSH PRIVILEGES;
 ```
 
+## Файл конфигурации
+
 Файл конфигурации состоит из как минимум трёх секций:
 - секция глобальных настроек
 - секция настроек подключения к БД
 - одна или несколько секций, описывающих, как строить сайтмап для страниц определенной категории
 
-Опишу эти опции последовательно:
+Опишу эти секции последовательно:
 
 ### Секция глобальных настроек
 
-Это обязательная секция, без неё просто непонятно что делать.
+Это обязательная секция, без неё скрипту делать нечего.
 
 ```
 [___GLOBAL_SETTINGS___]
@@ -99,9 +112,11 @@ limit_bytes = 50000000
 use_gzip = 1
 
 ; [НЕОБЯЗАТЕЛЬНАЯ ОПЦИЯ]
-; выводить ли информацию о генерации файлов карт? По умолчанию: выводить.
+; выводить ли информацию о генерации файлов карт? По умолчанию: выводить. 
+; перекрывается ключом `--verbose`
 logging = 1
 
+; [НЕОБЯЗАТЕЛЬНАЯ ОПЦИЯ]
 ; формат представления даты. Допустимые значения:
 ;   iso8601 - дата в формате W3C Datetime (2004-12-23T18:00:15+00:00)
 ; * YMD - дата в формате Y-m-d (2004-12-23), этот формат используется по умолчанию (если опция не задана или содержит иное значение)
@@ -111,6 +126,13 @@ date_format_type = 'iso8601'
 ; суффикс для секции с настройками подключения
 ; Пустое значение возможно только в том случае, если ВСЕ секции берут данные из файлов. Но все равно будет выведено предупреждение.
 db_section_suffix = 'DATABASE'
+
+; [НЕОБЯЗАТЕЛЬНАЯ ОПЦИЯ, ТРИ ВАРИАНТА ВОЗМОЖНЫХ ЗНАЧЕНИЙ]
+; Указывает, как создавать путь к корню сайта в sitemap
+; 0 или не задано: описание локейшена к корню сайта не создается. В этом случае рекомендуется создать секцию с описанием статичных ссылок на пути (см. ниже, тип секции `file`), а в файле указать "/" как путь к корню
+; 1 (число) - создается файл сайтмэпа root.xml.gz,  который будет содержать единственный локейшен к корню сайта
+; foobar (строка) - воспринимается как имя файла сайтмэпа, который будет содержать единственный локейшен к корню сайта 
+include_root_page = 1
 ```
 
 ### Секция настроек подключения к БД
@@ -279,14 +301,13 @@ lastmod = 'NOW()'
 radical = 'countries'
 ```
 
-Пустая строчка в текстовом файле-источнике означает, очевидно, пустую строку. Так, в примере конфигурации описана секция [static], в которой
-определен как источник данных файл `data.staticpages.txt`. Пустая строчка в этом файле означает, что необходимо сгенерировать ссылку на корневую
-страницу сайта.
-
-#### Пример секции: данные о страницах берутся из CSV-файла
-
-@todo: в разработке
+Пустая строчка в текстовом файле-источнике означает, очевидно, пустую строку, хотя так делать не рекомендуется.
 
+Если в статическом файле нужно указать путь к корню сайта - следует добавить строчку
+```
+/
+``` 
+Смотри пример в файле конфигурации `/docs/example/data.staticpages.txt`, секция `[static]` 
 
 #### Примечание
 
@@ -297,7 +318,6 @@ enabled = 0
 Любое другое значение или отсутствие этой строчки означает необходимость обработки секции.
 
 # Todo
-- Добавить источник данных: CSV с именованными столбцами.
 - Определиться, как задавать lastmod для страниц/строк, описанных в файлах (как источниках данных). Сейчас NOW() означает текущий таймштамп.
 - На данный момент если в обёртку `SitemapFileSaver::push()` не передаётся дата последней модификации - используется текущий таймштамп. Надо ли менять это поведение?
 - Определиться, нужно ли разрешить использовать индивидуальный `date_format_type` для каждой секции?

debian/changelog

@@ -0,0 +1,11 @@
+kwsitemapgenerator (2.0.3) stable; urgency=medium
+
+  * complete build system
+
+ -- Karel Wintersky <[email protected]>  Tue, 01 Oct 2019 17:39:09 +0300
+
+kwsitemapgenerator (2.0.2) stable; urgency=medium
+
+  * added changelog file
+
+ -- Karel Wintersky <[email protected]>  Tue, 01 Oct 2019 16:26:39 +0300

debian/compat

@@ -0,0 +1 @@
+9

debian/control

@@ -0,0 +1,13 @@
+Source: kwsitemapgenerator
+Section: unknown
+Priority: optional
+Maintainer: Karel Wintersky <[email protected]>
+Build-Depends: debhelper (>= 9)
+Standards-Version: 3.9.8
+Vcs-Git: https://github.com/KarelWintersky/kwTools.SitemapGenerator
+
+Package: kwsitemapgenerator
+Architecture: all
+Depends: php-cli, php-common, php-curl, php-fpm, php-json, php-mbstring, php-mysql, php-mysqli, php-pdo, php-xml, php-zip, composer
+Description: kwTools SitemapGenerator
+ kwTools SitemapGenerator

debian/rules

@@ -0,0 +1,23 @@
+#!/usr/bin/make -f
+# See debhelper(7) (uncomment to enable)
+# output every command that modifies files on the build system.
+#export DH_VERBOSE = 1
+
+# see FEATURE AREAS in dpkg-buildflags(1)
+#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
+
+# see ENVIRONMENT in dpkg-buildflags(1)
+# package maintainers to append CFLAGS
+#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
+# package maintainers to append LDFLAGS
+#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
+
+%:
+	dh $@
+
+override_dh_auto_install:
+	$(MAKE) install DESTDIR=$(CURDIR)/debian/kwsitemapgenerator
+
+override_dh_auto_build:
+
+override_dh_usrlocal:

debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

production/config.sitemap+db.ini.example → docs/example/config.sitemap+db.ini.example

@@ -10,6 +10,7 @@ use_gzip = 1
 logging = 1
 date_format_type = 'iso8601'
 db_section_suffix = 'DATABASE'
+include_root_page = 1
 
 [___GLOBAL_SETTINGS:DATABASE___]
 driver   = 'mysql'
@@ -85,7 +86,7 @@ url_priority = '0.5'
 url_changefreq = 'daily'
 lastmod = 'NOW()'
 
-; статические страницы (пустая строчка в начале файла со списком страниц означает корень сайта)
+; статические страницы (пустая строчка или одинокий слэш в строке означает ссылку на корень сайта, перекрывается опцией `include_root_page = 1` в глобальной секции)
 [static]
 radical = 'static'
 source = 'file'

production/data.staticpages.txt → docs/example/data.staticpages.txt

@@ -1,4 +1,4 @@
-
+/
 about/
 search/
 terms/