Концепція, опис сутності
Концепція, опис сутності
При створенні інтернет-проектів на платформі Bitrix Framework доступний великий функціонал "з коробки", використовувати який можна за допомогою викликів API відповідних модулів. При цьому кожен модуль в концепції фреймворка є самостійною робочою одиницею, яка забезпечує вирішення певного кола завдань.
Як правило, API кожного модуля розробляється виходячи із специфіки завдань, і нерідко формат викликів відрізняється від модуля до модуля. Щоб звести ці відмінності до мінімуму базовий функціонал, який присутній практично в кожному модулі, стандартизований. Це CRUD-операції: Create, Read, Update, Delete (створення, читання, оновлення та видалення даних).
концепція сутностей
Сутність - сукупність колекції об'єктів з властивою їм базової (низкоуровневой) бізнес-логікою. Сутність має набір характеристик, значення яких підпорядковуються певних правил обробки.
Наприклад, сутність Користувач - це безліч користувачів з набором полів:
При цьому ID автоматично видається базою даних, Ім'я та Прізвище обмежені довжиною 50 символів, Логін повинен складатися тільки з латинських букв, цифр і знака підкреслення і так далі.
Замість програмування кожної такої сутності, ми б хотіли описувати її в певному форматі. Такий опис оброблялося б ядром системи, було для нього свого роду конфігурацією:
Наприклад, схожим чином можна описати каталог книг, в якому система сама буде стежити за коректністю цілісністю даних: перевіряти формат і входження в діапазон допустимих значень.
типізація полів
Для конфігурації сутностей не використовуються засоби розмітки (xml, yml і т.п.), замість цього використовується php. Такий варіант дає максимум можливостей розвитку і гнучкості.
Так виглядає визначення типів даних з наведеного вище прикладу:
Увага! Незважаючи на те, що в прикладі під сутністю розуміється Книга (Book), до імені класу дописаний постфікси: BookTable. Це зроблено спеціально - ім'я описового класу суті завжди має завершуватися словом Table. Основне ім'я Book в цьому ж просторі імен вважається зарезервованим, в майбутньому передбачається використовувати основне ім'я (в даному випадку - клас Book) для представлення елементів сутності у вигляді об'єктів (в даний момент дані сутності представлені масивами, як і в старих методах getList).
За опис структури суті відповідає метод getMap (). який повертає масив екземплярами полів.
Кожен тип поля представлений у вигляді класу-спадкоємця Entity \ ScalarField - ці поля працюють з простими скалярними значеннями, які зберігаються в базу даних "як є". За замовчуванням є 8 таких типів:
В рамках дотримання стандартів кодування рекомендується називати поля у верхньому регістрі. Імена повинні бути унікальними в рамках однієї сутності.
Як правило, в конструкторі поля першим параметром передається ім'я поля, а другим параметром - додаткові налаштування. Загальні настройки будуть розглянуті далі в цій главі, але є і специфічна настройка для BooleanField і EnumField:
Для BooleanField, оскільки true і false не можуть зберігатися в такому вигляді в БД, задається маппинг значень у вигляді масиву, де перший елемент замінює при зберіганні false, а другий true.
Примітка. при описі сутності можна задати ім'я таблиці в методі getTableName. в даному прикладі це `my_book`. Якщо не визначити цей метод, то ім'я таблиці буде сформовано автоматично з неймспейса і назви класу, для даної суті це буде `b_somepartner_mybookscatalog_book`.
Primary autoincrement required
У більшості випадків у сутності є первинний ключ по одному полю. Він же, як правило, є Автоінкрементний. Щоб розповісти про це сутності, необхідно скористатися параметрами в конструкторі поля:
Примітка. складовою первинний ключ теж можливий. Наприклад, у відносинах двох сутностей складовим ключем будуть ID обох сутностей. Детальніше дізнатися про це і подивитися приклад можна в розділі N: M relations.
Так заявляється про приналежність поля до первинному ключу. Завдяки цій опції, сутність контролюватиме вставку даних і не дасть додати запис без вказівки значення для первинного ключа. При оновленні і видаленні записів їх можна буде ідентифікувати тільки по первинному ключу.
Часто не вказується явно значення ID, а воно виходить з бази даних вже після успішного додавання записи. У такому випадку потрібно повідомити про це сутності:
Прапор 'autocomplete'. для сутності означає, що при додаванні нового запису не потрібно вимагати від розробника установки значення для даного поля. За замовчуванням, така вимога застосовується тільки до полів з первинного ключа, але можна попросити систему вимагати установку і будь-якого іншого поля:
Тепер можна буде додати нову книгу, не вказавши її ISBN код.
Маппінг імені колонки
При описі суті для вже наявної таблиці може виникнути бажання по-іншому назвати колонку. Наприклад, спочатку в таблиці `my_book` поле ISBN називалося як ISBNCODE, і старий код використовує цю назву колонки в SQL запитах. Якщо в новому API необхідно оптимізувати назву до більш Новомосковскемого ISBN, то в цьому допоможе параметр 'column_name':
Бувають і інші випадки, коли в одному фізичному колонці в таблиці зберігаються різні за змістом значення. В такому випадку можна створити кілька полів суті, у яких буде однаковий 'column_name'.
вирази ExpressionField
Передбачено не тільки зберігання даних як є, але і їх перетворення при вибірці. Припустимо, виникла потреба нарівні з датою видання відразу ж отримувати вік книги в днях. Зберігати це число в БД накладно: доведеться щодня перераховувати оновлювати дані. Можна просто вважати вік на стороні бази даних:
Для цього потрібно описати по суті віртуальне поле, значення якого базується на SQL-виразі з іншим полем або полями:
Першим параметром, як і у інших полів, задається ім'я. Другим параметром потрібно передати текст SQL виразу, але при цьому інші поля суті потрібно замінити на плейсхолдери згідно формату sprintf. Третім параметром потрібно передати масив з іменами полів суті в певному порядку, який був заданий у вираженні.
Примітка. як плейсхолдеров рекомендується використовувати `% s` або`% 1 $ s`, `% 2 $ s` і так далі. Наприклад, коли в вираженні EXPR бере участь кілька полів (FIELD_X + FIELD_Y) * FIELD_X. то вираз можна описати так: '(% s +% s) *% s', [FIELD_X, FIELD_Y, FIELD_X]; або так: '(% 1 $ s +% 2 $ s) *% 1 $ s', [FIELD_X, FIELD_Y].
Дуже часто вирази можуть застосовуватися для агрегації даних (наприклад, COUNT (*) або SUM (FIELD)), такі приклади будуть розглянуті в главі Вибірка даних.
Примітка. expression поля можна використовувати тільки при вибірці даних: вибирати, фільтрувати, групувати і сортувати по ним. Оскільки фізично таких колонок в таблиці БД немає, то записати значення поля нікуди: система згенерує виняток.
призначені для користувача поля
Крім полів ScalarField і ExpressionField. сутність може містити Користувальницькі поля. Вони конфигурируются через Адміністративний інтерфейс і не вимагають додаткового опису на стороні сутності. Все, що потрібно вказати по суті, це обраний Об'єкт призначеного для користувача поля:
Надалі саме цей ідентифікатор потрібно вказувати при прикріпленні користувальницьких полів до суті:
Таким чином, можна вибирати і оновлювати значення користувальницьких полів нарівні зі значеннями штатних полів суті.
За результатами даного розділу отримана наступна сутність:
Таким чином можна описати по суті звичайні скалярні поля, виділити з них первинний ключ, вказати Автоінкрементний поля і які поля повинні бути обов'язково заповнені. При розбіжності імені колонки в таблиці і бажаного імені по суті буде можливість залагодити цей момент.
Увага! Метод getMap використовується тільки як отримання первинної конфігурації суті. Якщо ви хочете отримати дійсний список полів суті, скористайтеся методом BookTable :: getEntity () -> getFields ().
Залишилося тільки зафіксувати код суті в проекті. Згідно із загальними правилами іменування файлів в D7, код суті потрібно зберегти у файлі: local / modules / somepartner.mybookscatalog / lib / book.php
Після чого система автоматично буде підключати файл при знаходженні викликів класу BookTable.