|
1 | 1 | # Developers documentation |
| 2 | + |
| 3 | + |
| 4 | +## 1 Правила разработки |
| 5 | +При доработке модуля необходимо придерживаться следующих правил: |
| 6 | + |
| 7 | +### 1.1. Хуки и фильтры |
| 8 | +- При создании **новых хуков, фильтров, AJAX-хуков** добавляйте префикс, который идентифицирует принадлежность к плагину. |
| 9 | +- Используемый префикс: `retailcrm_` |
| 10 | +- **Пример правильного формата**: |
| 11 | + ```php |
| 12 | + wp_ajax_retailcrm_do_upload |
| 13 | + ``` |
| 14 | + |
| 15 | +### 1.2 Внешние источники |
| 16 | +Запрещается получать файлы (JSON, изображения и т.п.) из удалённых источников. |
| 17 | +Вместо этого — добавлять их в сам плагин. |
| 18 | + |
| 19 | +### 1.3 Переводы |
| 20 | +- Всегда используйте идентичный идентификатор перевода `woo-retailcrm`: |
| 21 | + ```php |
| 22 | + __('I agree to receive promotional newsletters', 'woo-retailcrm') |
| 23 | + ``` |
| 24 | +- Не подставлять переменные напрямую в перевод а использовать `sprintf()` или `printf()`: |
| 25 | + ```php |
| 26 | + __($test, 'woo-retailcrm') // запрещено |
| 27 | + |
| 28 | + printf( // Разрешено |
| 29 | + /* translators: %s: First name of the user */ |
| 30 | + esc_html__( 'Hello %s, how are you?', 'woo-retailcrm' ), |
| 31 | + esc_html( $user_firstname ) |
| 32 | + ); |
| 33 | + |
| 34 | + sprintf( // если параметров больше одного, используйте нумерацию |
| 35 | + 'Fill order data: WC_Customer ID: %1$s email: %2$s WC_Order ID: %3$s', |
| 36 | + $wcCustomerId, |
| 37 | + $wcCustomerEmail, |
| 38 | + $wcOrder->get_id() |
| 39 | + ) |
| 40 | + ``` |
| 41 | + |
| 42 | +### 1.4 Экранирование переводов |
| 43 | +Не использовать стандартную функцию `__` без экранирования. Вместо этого: |
| 44 | + ```php |
| 45 | + esc_html__() // Экранирование html тегов |
| 46 | + esc_attr__() // Экранирование аттрибутов html элементов |
| 47 | + ``` |
| 48 | + |
| 49 | +### 1.5 Экранирование вывода данных |
| 50 | +При выводе данных (например, с помощью `echo`) необходимо выполнять экранирование с помощью методов: |
| 51 | +```php |
| 52 | +esc_html() // Экранирование html тегов |
| 53 | +esc_attr() // Экранирование аттрибутов html элементов |
| 54 | +esc_js() // Экранирование js |
| 55 | +``` |
| 56 | +### 1.6. Очистка входящих данных |
| 57 | +- При использовании `filter_input()` обязательно указывать третий параметр — предполагаемый тип значения: |
| 58 | + ```php |
| 59 | + filter_input(INPUT_POST, 'Step', FILTER_SANITIZE_NUMBER_INT); |
| 60 | + ``` |
| 61 | +- При получении параметров через `$_GET`, `$_POST`, `$_REQUEST`: |
| 62 | + ```php |
| 63 | + $test = wp_unslash($_GET['value']); // Удаление слешей |
| 64 | + sanitize_text_field($_GET['value']); // удаление параметра |
| 65 | + ``` |
| 66 | +### 1.7 AJAX-запросы |
| 67 | +- Обязательно генерировать `nonce-токены`: |
| 68 | + ```php |
| 69 | + $token = wp_create_nonce('woo-retailcrm-admin-nonce'); // пример названия для токена. Должен быть уникальным для каждой логической цепочки. |
| 70 | + ``` |
| 71 | +- Проверять `nonce-токен` при получении запроса: |
| 72 | + ```php |
| 73 | + heck_ajax_referer('woo-retailcrm-admin-nonce', '_ajax_nonce', false); // _ajax_nonce - базовый ключ параметра WordPress, в котором хранится nonce-токен |
| 74 | + ``` |
| 75 | +- Если запрос требует прав `администратора/менеджера` для выполнения действий, производить проверку: |
| 76 | + ```php |
| 77 | + current_user_can('manage_woocommerce'); |
| 78 | + current_user_can('manage_options'); |
| 79 | + ``` |
| 80 | + |
| 81 | +## 2 Проверка плагина после доработки |
| 82 | +Для проверки используйте плагин: [WordPress Plugin Check](https://wordpress.org/plugins/plugin-check/) (Устанавливается как плагин в WordPress) |
| 83 | +- Исправьте все несоответствия с тегом `ERROR` |
| 84 | +- Сообщения с тегом `WARNING` — исправлять по возможности |
0 commit comments