diff --git a/LICENSE.txt b/LICENSE similarity index 96% rename from LICENSE.txt rename to LICENSE index 8a1308d..28f5bbb 100644 --- a/LICENSE.txt +++ b/LICENSE @@ -1,7 +1,7 @@ The MIT License (MIT) -Copyright (c) [2013] [Dmitry Shulgachik] +Copyright (c) [2017] [Dmitry Shulgachik] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/README.md b/README.md index 5bcfbec..5454ff8 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,22 @@ # Стандарты разработки на платформе 1С-Битрикс -В данном руководстве описаны рекомендуемые техники при разработке на платформе [1С-Битрикс](http://www.1c-bitrix.ru/) / 1C-Bitrix (далее - Битрикс). +> В данном руководстве описаны рекомендуемые техники при разработке на платформе [1С-Битрикс](http://www.1c-bitrix.ru/) / 1C-Bitrix (далее - Битрикс). Если вы заметили ошибку и хотите внести исправление или дополнение, пожалуйста, не стесняйтесь делать `pull request` или связываться напрямую. Приветствуется любая помощь. -## PHP - -* Код PHP должен быть написан в соответствии со стандартом [PSR-1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md). - -* Стиль написания кода должен соответствовать стандарту [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md). +## PHPs +* Код PHP должен быть написан в соответствии со стандартом [PSR-1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md); +* Стиль написания кода должен соответствовать стандарту [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md); * В конечном итоге придерживаемся [правил форматирования](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=5759) (ядро D7) от разработчиков системы. ## Оформление исходного кода -- Используйте кодировку `UTF-8` без `BOM` для файлов с исходным кодом. -- Используйте Unix-style окончания строк `LF`. Никаких `CR+LF`. -- Используйте сокращенные теги ` @@ -27,68 +24,64 @@ // good ``` - -- Используйте **ТАБ** для каждого отступа. Никаких пробелов для блоков кода. +* Используйте TAB для каждого отступа. Никаких пробелов для блоков кода. ## Общие положения -- При добавлении кода в файл `init.php` группируйте код в классы и выносите их в отдельные файлы. - -- При подключении файлов используйте только функции Битрикса. Цитата: -> Поддержка Bitrix Framework русских (и прочих) символов в названиях публичных файлов накладывает определённые ограничения на работу: -> недопустимы прямые вызовы -> -> - к файлам, имена которых выбираются пользователями, -> - к папкам, имена которых выбираются пользователями, -> - к файлам и папкам, которые могут лежать в папках, имена которых выбираются пользователями. -> Недопустимы вызовы любых прямых методов работы с файловой системой: include, require, fopen, filesize, unlink, file_exists и т.д. [Документация Битрикс CBXVirtualIo](http://dev.1c-bitrix.ru/api_help/main/reference/cbxvirtualio/index.php) - - `init.php` +* При добавлении кода в файл `init.php` группируйте код в классы и выносите их в отдельные файлы; +* При подключении файлов используйте только функции Битрикса; + + > Поддержка Bitrix Framework русских (и прочих) символов в названиях публичных файлов накладывает определённые ограничения на работу: + > + > * недопустимы прямые вызовы + > * к файлам, имена которых выбираются пользователями, + > * к папкам, имена которых выбираются пользователями, + > * к файлам и папкам, которые могут лежать в папках, имена которых выбираются пользователями. + > + > Недопустимы вызовы любых прямых методов работы с файловой системой: include, require, fopen, filesize, unlink, file_exists и т.д. + > + > _Источник: [Документация Битрикс CBXVirtualIo](http://dev.1c-bitrix.ru/api_help/main/reference/cbxvirtualio/index.php)_ + ```php + // init.php + // bad // SomeClass include('../some_file.php'); - + //good // SomeClass $APPLICATION->GetFileContent('../some_file.php'); ``` -* Не используйте **цифровые значения** в GetList, GetByID и схожих методах, которые принимают различные ID. Создайте файл со всеми необходимыми константами и используйте их имена. - +* Не используйте **цифровые значения** в GetList, GetByID и схожих методах, которые принимают различные ID. Создайте файл со всеми необходимыми константами и используйте их имена; ```php // bad $comments = CIBlockElement::GetList([], ["IBLOCK_ID" => 12]); ``` - 1. У каждой константы должно быть **говорящее** имя и комментарий. - 2. Файл `constants.php`: - - ```php - // ИБ с комментариями пользователей - const COMMENTS_IBLOCK_ID = 12; - ``` - 3. Подключите этот файл в `init.php` - - ```php - //Константы проекта - $APPLICATION->GetFileContent($_SERVER["DOCUMENT_ROOT"] . '/bitrix/php_interface/includes/constants.php'); - ``` - 4. Используйте константу - - ```php - $comments = CIBlockElement::GetList([], ["IBLOCK_ID" => COMMENTS_IBLOCK_ID]); - ``` - -- Используйте [Bitrix IBlock Tools](https://github.com/xescoder/bitrix-iblock-tools), [обсуждение](http://habrahabr.ru/post/185080/). -- При выборках данных (например, [GetList](http://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/getlist.php)) **обязательно** указывайте поля, которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля: - +* У каждой константы должно быть **говорящее** имя и комментарий +* Файл `constants.php`: + ```php + // ИБ с комментариями пользователей + const COMMENTS_IBLOCK_ID = 12; + ``` +* Подключите этот файл в `init.php` + ```php + //Константы проекта + $APPLICATION->GetFileContent($_SERVER["DOCUMENT_ROOT"] . '/bitrix/php_interface/includes/constants.php'); + ``` +* Используйте константу + ```php + $comments = CIBlockElement::GetList([], ["IBLOCK_ID" => COMMENTS_IBLOCK_ID]); + ``` +* Используйте [Bitrix IBlock Tools](https://github.com/xescoder/bitrix-iblock-tools), [обсуждение](http://habrahabr.ru/post/185080/); +* При выборках данных (например, [GetList](http://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/getlist.php)) **обязательно** указывайте поля, которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля: ```php // good - Обязательно указывайте поля для выборки $arSelect = ["ID", "IBLOCK_ID", "NAME", "DATE_ACTIVE_FROM"]; ... $res = CIBlockElement::GetList([], $arFilter, false, [], $arSelect); ``` -- При необходимости выбрать несколько элементов по ID, **обязательно** используйте GetList вместо GetByID: - +* При необходимости выбрать несколько элементов по ID, **обязательно** используйте GetList вместо GetByID: ```php // bad $element1 = CIBlockElement::GetByID(1); @@ -96,21 +89,18 @@ // good $elements = CIBlockElement::GetList([], [ - "ID" => [1, 2] - ]); + "ID" => [1, 2] + ]); ``` -- Не используйте **прямые запросы к базе** данных, вся работа только через [API](http://dev.1c-bitrix.ru/api_help/). -- Если к файлу **не предусмотрен** прямой доступ через WEB, в первой строке файла добавьте: - +* Не используйте **прямые запросы к базе** данных, вся работа только через [API](http://dev.1c-bitrix.ru/api_help/); +* Если к файлу **не предусмотрен** прямой доступ через WEB, в первой строке файла добавьте: ```php ``` ## Отладка -**Важно** - - *Логирование замедляет работу системы и может являться брешью в безопасности* +> _Логирование замедляет работу системы и может являться брешью в безопасности_ ### Вывод на экран @@ -118,23 +108,19 @@ ### Вывод в файл -* [api_help](http://dev.1c-bitrix.ru/api_help/main/functions/debug/index.php) - -1. Определите константу `LOG_FILENAME` в файле `/bitrix/php_interface/dbconn.php`, задавая путь к лог-файлу за пределами `DOCUMENT_ROOT`. +Использование [api_help](http://dev.1c-bitrix.ru/api_help/main/functions/debug/index.php). +* Определите константу `LOG_FILENAME` в файле `/bitrix/php_interface/dbconn.php`, задавая путь к лог-файлу за пределами `DOCUMENT_ROOT`: ```php // определяем константу LOG_FILENAME, в которой зададим путь к лог-файлу define("LOG_FILENAME", $_SERVER["DOCUMENT_ROOT"]."/../log.txt"); ``` - -2. Отправьте сообщение в лог - +* Отправьте сообщение в лог: ```php AddMessage2Log("Произвольный текст сообщения", "module_id"); ``` Пример: - ```php AddMessage2Log( print_r($arResult, true) ); ``` @@ -142,61 +128,49 @@ ### SQL * Определите переменную `DBDebugToFile` для логирования всех SQL запросов. - ```php $DBDebugToFile = true; ``` ## Работа с компонентами -- Шаблонам компонентов давайте осмысленные названия и в каждом проекте придерживайтесь общего стиля. Например, `раздел/страница_сайта.Название.Тип` - +* Шаблонам компонентов давайте осмысленные названия и в каждом проекте придерживайтесь общего стиля. Например, `раздел/страница_сайта.Название.Тип` Примеры: - - - `index.user.auth` - - `profile.orders.list` - - `cart.products.additional` - -- Стандартные компоненты **не модифицируются**. Если возникнет такая необходимость — создайте копию компонента в своем пространстве имен в каталоге `/дщсфд/components/`. -- НЕ РЕКОМЕНДУЕТСЯ делать любые манипуляции с данными в файле `template.php`. При необходимости правки логики стандартных компонентов, но недостаточной для того, что делать свой используются файлы [result_modifier.php](http://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2830&LESSON_PATH=3913.4565.2830) и [component_epilog.php](http://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2975&LESSON_PATH=3913.4565.2975) -- РЕКОМЕНДУЕТСЯ использовать файлы `style.css` и `script.js` в шаблонах только если они переопределяют стандартное поведение схожих элементов. РЕКОМЕНДУЕТСЯ оставить комментарий об этой особенности. + * `index.user.auth` + * `profile.orders.list` + * `cart.products.additional` +* Стандартные компоненты **не модифицируются**. Если возникнет такая необходимость — создайте копию компонента в своем пространстве имен в каталоге `/дщсфд/components/`. +* **НЕ РЕКОМЕНДУЕТСЯ** делать любые манипуляции с данными в файле `template.php`. При необходимости правки логики стандартных компонентов, но недостаточной для того, что делать свой используются файлы [result_modifier.php](http://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2830&LESSON_PATH=3913.4565.2830) и [component_epilog.php](http://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2975&LESSON_PATH=3913.4565.2975) +* **РЕКОМЕНДУЕТСЯ** использовать файлы `style.css` и `script.js` в шаблонах только если они переопределяют стандартное поведение схожих элементов. РЕКОМЕНДУЕТСЯ оставить комментарий об этой особенности. ### Кэширование -- Кэширование компонентов **не отключается**. Практически не существует задач, которые нельзя решить с включенным кэшированием. - - *Исключение:* - - - Во время разработки полностью отключайте кэширование - это сэкономить вам много времени. - -- Подключайте js и css файлы только через предназначенный для этого API: - - [CMain::AddHeadScript](http://dev.1c-bitrix.ru/api_help/main/reference/cmain/addheadscript.php) - - [CMain::SetAdditionalCSS](http://dev.1c-bitrix.ru/api_help/main/reference/cmain/setadditionalcss.php) - -- Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров: - - Chrome [Clear Cache](https://chrome.google.com/webstore/detail/clear-cache/cppjkneekbjaeellbfkmgnhonkkjfpdn) - -- НЕЛЬЗЯ вставлять код вызова компонента внутрь файла `template.php` другого компонента. - - *Это противоречит идеологии разделения даннах и представления (см. выше) и влечет двойное кэширование.* +* Кэширование компонентов **не отключается**. Практически не существует задач, которые нельзя решить с включенным кэшированием: + * **Исключение:** Во время разработки полностью отключайте кэширование - это сэкономить вам много времени +* Подключайте js и css файлы только через предназначенный для этого API: + * [CMain::AddHeadScript](http://dev.1c-bitrix.ru/api_help/main/reference/cmain/addheadscript.php); + * [CMain::SetAdditionalCSS](http://dev.1c-bitrix.ru/api_help/main/reference/cmain/setadditionalcss.php). +* Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров: + * Chrome [Clear Cache](https://chrome.google.com/webstore/detail/clear-cache/cppjkneekbjaeellbfkmgnhonkkjfpdn). +* **НЕЛЬЗЯ** вставлять код вызова компонента внутрь файла `template.php` другого компонента. + * **Внимание:** Это противоречит идеологии разделения даннах и представления (см. выше) и влечет двойное кэширование. ## Работа с шаблонами -- РЕКОМЕНДУЕТСЯ использовать минимальное количество шаблонов. -- РЕКОМЕНДУЕТСЯ подключать `header.php` и `footer.php` из одного места для всех шаблонов, если это позволяет дизайн и верстка. -- РЕКОМЕНДУЕТСЯ общие картинки, скрипты и стили шаблонов сохранять в одном месте, например, в `/bitrix/templates/.default/`. +* РЕКОМЕНДУЕТСЯ использовать минимальное количество шаблонов; +* РЕКОМЕНДУЕТСЯ подключать `header.php` и `footer.php` из одного места для всех шаблонов, если это позволяет дизайн и верстка; +* РЕКОМЕНДУЕТСЯ общие картинки, скрипты и стили шаблонов сохранять в одном месте, например, в `/bitrix/templates/.default/`. ### Структура шаблона -- В каталоге шаблона остаются только необходимые для Битрикс файлы - `header.php`, `footer.php`, `styles.css` и т.д. -- Включаемые файлы располагаются в каталоге `includes` -- Все дополнительные файлы (скрипты, изображения и т.д.) располагаются в каталоге `assets`: - - `js` - свои скрипты и однофайловые библиотеки - - `css` - свои стили и однофайловые библиотеки - - `images` - изображения, спрайты, иконки - - `fonts` - шрифты - - остальные библиотеки и фреймворки располагаются в каталогах, названия которых совпадают с названием и версией библиотеки, при этом сохраняется внутренняя структура дистрибутива. - - *Документацию, примеры и доп. файлы можно удалить.* +* В каталоге шаблона остаются только необходимые для Битрикс файлы - `header.php`, `footer.php`, `styles.css` и т.д; +* Включаемые файлы располагаются в каталоге `includes`; +* Все дополнительные файлы (скрипты, изображения и т.д.) располагаются в каталоге `assets`: + * `js` - свои скрипты и однофайловые библиотеки; + * `css` - свои стили и однофайловые библиотеки; + * `images` - изображения, спрайты, иконки; + * `fonts` - шрифты; + * остальные библиотеки и фреймворки располагаются в каталогах, названия которых совпадают с названием и версией библиотеки, при этом сохраняется внутренняя структура дистрибутива (*Документацию, примеры и доп. файлы можно удалить*). Пример: @@ -231,13 +205,14 @@ ## Работа с инфоблоками -- Названия свойств инфоблоков должны быть: - 1. в верхнем регистре; - 2. осмысленными (используйте связку сущность_наименование); - 3. слова разделаются [подчеркиванием](http://ru.wikipedia.org/wiki/%D0%9F%D0%BE%D0%B4%D1%87%D1%91%D1%80%D0%BA%D0%B8%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5). - - Пример: +Названия свойств инфоблоков должны быть: + +* в верхнем регистре; +* осмысленными (используйте связку сущность_наименование); +* слова разделаются [подчеркиванием](http://ru.wikipedia.org/wiki/%D0%9F%D0%BE%D0%B4%D1%87%D1%91%D1%80%D0%BA%D0%B8%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5). + +Пример: - - Имя пользователя: `USER_NAME` - - Валюта заказа: `ORDER_CURRENCY` - - Список заказов: `ORDER_LIST` +* Имя пользователя: `USER_NAME` +* Валюта заказа: `ORDER_CURRENCY` +* Список заказов: `ORDER_LIST` diff --git a/package.json b/package.json new file mode 100644 index 0000000..a0cd44d --- /dev/null +++ b/package.json @@ -0,0 +1,9 @@ +{ + "name": "bitrix-style-guide", + "version": "1.0.0", + "description": "В данном руководстве описаны рекомендуемые техники при разработке на платформе 1С-Битрикс", + "main": "readme.md", + "repository": "git@github.com:ancorp/BitrixCM.git", + "author": "ancorp", + "license": "MIT" +} diff --git a/settings.md b/settings.md index 5cb2363..dcdf1c2 100644 --- a/settings.md +++ b/settings.md @@ -1,62 +1,62 @@ -##Общие параметры (минимальные) +# Параметры -- версия веб-сервера: Apache 2.2 -- включена обработка .htaccess (mod_rewrite) -- версия PHP 5.4 и выше -- **версия PHP 5.3 категорически не допускается (снята с поддержки, обновления безопасности не выпускаются)** -- Режим работы php - модуль apache (mod_php) -- время пинга от потенциального пользователя до сервера - менее 150мс -- версия ядра Битрикс 14 и выше +## Общие параметры. Минимальные -##Общие параметры (рекомендованные) +* версия веб-сервера: Apache 2.2; +* версия PHP 5.4 и выше; +* версия ядра Битрикс 14 и выше. +* **версия PHP 5.3 категорически не допускается (снята с поддержки, обновления безопасности не выпускаются)**; +* Режим работы php - модуль apache (mod_php); +* включена обработка .htaccess (mod_rewrite); +* время пинга от потенциального пользователя до сервера - менее 150мс; -все что в минимальных, плюс +## Общие параметры. Рекомендованные -- версия PHP 5.6 и выше -- версия ядра Битрикс 16 и выше -- доступ к аккаунту хостинга по ssh/sftp -- время пинга от потенциального пользователя до сервера - менее 100мс -- включенный акселератор opcache -- оценка производительности конфигурации по тестированию Битрикс (версии 15) - не ниже 20 +Все что в минимальных, плюс: +* версия PHP 5.6 и выше +* версия ядра Битрикс 16 и выше +* включенный акселератор opcache +* время пинга от потенциального пользователя до сервера - менее 100мс +* доступ к аккаунту хостинга по ssh/sftp +* оценка производительности конфигурации по тестированию Битрикс (версии 15) - не ниже 20 -##Установки PHP (минимальные) +## Установки PHP. Минимальные ```ini -safe_mode = Off -short_open_tag = On -realpath_cache_size = 4096k ; и больше -memory_limit = 128M default_charset = UTF-8 mbstring.func_overload = 2 mbstring.internal_encoding = UTF-8 +memory_limit = 128M +realpath_cache_size = 4096k ; и больше +safe_mode = Off +short_open_tag = On ``` -###при использовании opcache +### Использование opcache ```ini -opcache.validate_timestamps = 1 -opcache.revalidate_freq = 0 +opcache.revalidate_freq = 0 +opcache.validate_timestamps = 1 ``` -##Установки PHP (рекомендованные) - -- доступная память (memory_limit) - - для визитки, каталога - не менее 128 Mb - - для магазина - не менее 256 Mb -- позволить загрузку файлов (file_uploads) -- показывать ошибки (display_errors) +## Установки PHP. Рекомендованные -##Требуемые модули PHP +* доступная память (memory_limit) + * для визитки, каталога - не менее 128 Mb + * для магазина - не менее 256 Mb +* позволить загрузку файлов (file_uploads) +* показывать ошибки (display_errors) -- Multibyte String (mbstring) -- MySQL (mysql/mysqli) -- поддержка регулярных выражений (Perl-Compatible) +## Требуемые модули PHP +* Multibyte String (mbstring) +* MySQL (mysql/mysqli) +* поддержка регулярных выражений (Perl-Compatible) -##Рекомендуемые модули PHP +## Рекомендуемые модули PHP -- MCrypt -- Zlib Compression -- Библиотека GD (функции для работы с графикой) -- Free Type Library +* [Free Type Library](http://php.net/manual/ru/image.installation.php) +* [MCrypt](http://php.net/manual/ru/book.mcrypt.php) +* [Zlib Compression](http://php.net/manual/ru/book.zlib.php) +* [Библиотека GD](http://php.net/manual/ru/book.image.php) (функции для работы с графикой)