Ներածություն Entity API-ին Drupal 8-ում

Drupal 8-ի Entity համակարգը

Entity-ները տիպավորված դասեր են մեթոդներով

Նախապատմություն

Entity համակարգը ներմուծվեց Drupal 7-ի զարգացման վերջին փուլում՝ Entity-ների բազային ստանդարտ լիցքավորման մեթոդներով: entity.module-ը ավելի զարգացրեց API-ն՝ ավելացնելով Entity-ների պահպանման, ջնջման և այլ բարելավումներ:

Աշխատանքների մեծամասնությունը այժմ ներառված է Drupal 8-ում։ Entity-ի վավերացմանը այժմ կատարվում է առանձին API-ի միջոցով (որը կարող է վավերացնել, օրինակ, REST-ով պահպանված entity, ոչ միայն ֆորմայի միջոցով):

Երկու տարբերակ

Բազային Entity տիպերը երկուսն են.

Կոնֆիգուրացիոն օբյեկտ
Կիրառվում է Կոնֆիգուրացիայի համակարգը, ունի թարգմանություններ, կարող է տրամադրել ադմինական նախնական կարգավորումներ: Կոնֆիգուրացիոն օբյեկտները պահվում են կոնֆիգուրացիայի տվյալների ընդհանուր աղյուսակում որպես տողեր:

Բովանդակային օբյեկտ
Կազմված է դաշտերից՝ ինչպես բազային, այնպես էլ հարմարեցված, կարող է ունենալ վերանայումներ և թարգմանություններ: Դրանք պահվում են հատուկ աղյուսակում՝ որի անունը համընկնում է entity-ի id-ին, իսկ սյունակները սահմանվում են baseFieldDefinitions մեթոդով:

Բանդլեր (Bundles)

Բանդլերը entity տիպի տարբերակը կամ ենթատիպն է: Օրինակ՝ node entity տիպի բանդլերները կարող են լինել «article» կամ «page» բովանդակության տիպեր։

Բանդլերը, որպես կանոն, ներկայացվում են կոնֆիգուրացիոն օբյեկտի միջոցով, թեև contributed մոդուլներում կան այլ մոտեցումներ: Node-ի դեպքում՝ article բանդլը կոնֆիգուրացիոն օբյեկտ է, որը պահպանում է տարբերությունները բովանդակության տիպերի միջև՝ ինչպես դաշտերի, այնպես էլ կարգավորումների տեսանկյունից: Երբ ստեղծում եք նոր entity տիպ բանդլերով, դուք պետք է ստեղծեք և բովանդակային entity, և կոնֆիգուրացիոն օբյեկտ, որը կառավարում է տարբերությունները բանդլերի միջև:

Անոտացիաներ (Annotations)

Նոր entity տիպ ստեղծելիս պետք է օգտագործեք Drupal-ի ներմուծված անոտացիաների համակարգը, որը տեղադրված է կենտրոնական կոդում: Անոտացիաները տեսքով նման են docblock մեկնաբանություններին դասերի վերևում, բայց դրանք վերծանվում և պահվում են Drupal-ի կողմից: Շատ առումներով դրանք փոխարինում են Drupal 7-ում օգտագործված հին ոճերին:

Անոտացիաների վերծանում

Անոտացիաները վերծանվում են runtime-ում Doctrine-ի անոտացիաների վերծանողով՝ որին վերածում է PHP օբյեկտի:

Սինտաքսիս. Անոտացիայի սինտաքսիսը շրջապատված է @ClassName() սինթաքսիսով, բաղկացած հիմնականում key/value զույգերից, կարող է պարունակել նաև զանգվածներ ծածկված փակագծերով: Վերին մակարդակի բանալիները չեն փակվում գրչակներով, իսկ զանգվածների բանալիները փակվում են: Յուրաքանչյուր զույգ պետք է լինի նոր տողում և ավարտվի ստորակետով: Կարող են օգտագործվել հատուկ ֆունկցիաներ, օրինակ @Translation() ֆունկցիան:

Սինտաքսիսից բացի, ահա անաշխատող օրինակ.

/**
 * @ContentEntityType(
 *   id = "my_entity_type_id",
 *   label = @Translation("My entity type label"),
 *   example_pair = "this_examples_value",
 *   example_array = {
 *     "array_key" = "array_value",
 *     "some_other_key" = "some_other_value",
 *   },
 * )
 */

Ընդհանուր վերին մակարդակի անոտացիաներ

Հանդիպակներ (Handlers)

Հանդիպակները սահմանվում են entity-ի անոտացիայում որպես զանգված: Դրանք թույլ են տալիս փոխանցել որոշակի մասեր entity-ի իրականացումից PHP դասերին, որոնք կզբաղվեն այդ ֆունկցիոնալությամբ:

Storage (Պահպանում) – կառավարում է entity-ի լիցքավորումը, պահպանումը և ջնջումը: Բովանդակային entity-ները ըստ ստանդարտ օգտագործում են Drupal\Core\Entity\Sql\SqlContentEntityStorage, կոնֆիգուրացիոն entity-ները՝ Drupal\Core\Config\Entity\ConfigEntityStorage: Կարելի է սահմանել սեփական պահպանում՝ ստանդարտ մեթոդների ընդլայնման համար: Օրինակ՝ լրացուցիչ մեթոդներ ավելացնելու համար՝ entity-ի վերանայումների հաշվելու կամ թարգմանությունների քանակը որոշելու համար։ Օրինակ: "storage" = "Drupal\node\NodeStorage",

Form (Ֆորմա) – entity-ի անոտացիայի form հանդիպակների համար կարելի է սահմանել տարբեր դասեր, որոնք կզբաղվեն entity-ի ավելացման, խմբագրման և ջնջման ձևերով: Օրինակ՝

"form" = {
  "add" = "Drupal\block\BlockForm",
  "edit" = "Drupal\block\BlockForm",
  "delete" = "Drupal\block\Form\BlockDeleteForm",
}

Կարելի է սահմանել նաև "default" ֆորման, որը կզբաղվի և ավելացման, և խմբագրման ձևերով: Սակայն ջնջման ֆորման սովորաբար տարբեր դաս է, քանի որ այն հանդիսանում է հաստատման ձև, որտեղ հարցվում է՝ «նպատակահարմար է արդյոք ջնջել»:

View builder – սահմանում է դասը, որը կզբաղվի entity-ի դիտման ներկայացմամբ վերջնական օգտագործողի համար: Օրինակ՝ Drupal 8-ում node entity-ի դիտումը կառավարվում է NodeViewBuilder դասով: Օրինակ: "view_builder" = "Drupal\node\NodeViewBuilder",

List builder – դաս, որը կկառավարի entity-ների ցանկի ներկայացումը ադմինիստրատիվ նպատակներով, օրինակ՝ admin/content էջում: Օրինակ՝ NodeListBuilder: Օրինակ: "list_builder" = "Drupal\node\NodeListBuilder",

Route provider – լրացուցիչ հանդիպակ, որը, եթե իրագործված է, կստեղծի entity-ի համար անհրաժեշտ երթուղիներ՝ փոխարինելով routing.yml-ում սահմանված երթուղիները: Route provider-ը գործում է entity-ի «links»-ի հետ համատեղ: Օրինակ:

"route_provider" = {
  "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
}

Access – հանդիպակ՝ entity-ի մուտքի թույլտվությունները դինամիկ ստուգելու համար: Հատուկ դաս է, որը իրականացնում է EntityAccessControlHandlerInterface-ը: Կենտրոնական Drupal-ը տրամադրում է EntityAccessControlHandler, բայց եթե ցանկանում եք ավելի վերահսկողություն, կարող եք ընդլայնել ձեր սեփական դասը: Օրինակ: "access" = "NodeAccessControlHandler",

Views data – հնարավորություն է տալիս entity-ին ընդլայնել Views մոդուլը իր հատուկ տվյալներով, օրինակ՝ ավելացնելով entity-ի baseFieldDefinitions-ը view-ների դաշտերի համար կամ կապելով աղյուսակները: Օրինակ: "views_data" = "Drupal\node\NodeViewsData",

Storage schema – հնարավորություն է տալիս փոփոխություններ կատարել entity-ի տվյալների բազայի պահպանման սխեմայում, օրինակ՝ ավելացնելով լրացուցիչ ինդեքսներ: Օրինակ: "storage_schema" = "Drupal\node\NodeStorageSchema",

Translation – փոխարինում է entity-ի ձևերի թարգմանության վարվողությունը: Օրինակ: "translation" = "Drupal\node\NodeTranslationHandler",

Լրիվ handlers-ի օրինակ:
Drupal-ի միջուկը տրամադրում է «տուփից դուրս» handlers, որոնք կարող եք օգտագործել, բայց հաճախ կցանկանաք ընդլայնել դրանք ձեր կարիքներով: Ահա լրիվ օրինակը.

handlers = {
  "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
  "list_builder" = "Drupal\Core\Entity\EntityListBuilder",
  "access" = "Drupal\Core\Entity\EntityAccessControlHandler",
  "views_data" = "Drupal\views\EntityViewsData",
  "storage" = "Drupal\Core\Entity\Sql\SqlContentEntityStorage",
  "storage_schema" = "Drupal\Core\Entity\Sql\SqlContentEntityStorageSchema",
  "translation" = "Drupal\content_translation\ContentTranslationHandler",
  "form" = {
    "default" = "Drupal\Core\Entity\ContentEntityForm",
    "add" = "Drupal\Core\Entity\ContentEntityForm",
    "edit" = "Drupal\Core\Entity\ContentEntityForm",
    "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
  },
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
  },
},

Հղումներ (Links)

Հղումները սահմանվում են entity-ի անոտացիայում զանգվածի տեսքով: Յուրաքանչյուր հղում ունի բանալի՝ որը սահմանում է URI, որտեղ կարող եք կառավարել entity տիպը կամ առանձին entity-ները: Այս հղումները գործում են ինչպես բովանդակության, այնպես էլ կոնֆիգուրացիոն entity-ների համար:

Օրինակ.

id = "node",
handlers = {
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider"
  }
},
links = {
  "canonical" = "/node/{node}",
  "add-page" = "/node/add",
  "add-form" = "/node/add/{node_type}",
  "edit-form" = "/node/{node}/edit",
  "delete-form" = "/node/{node}/delete",
  "collection" = "/admin/content",
},

Կատտոլիկ չէ, որ սա վերցված է Node մոդուլից, պարզապես օրինակ է:

Այս հղումների ստեղծումը ինքնաբերաբար երթուղիներ չի ստեղծում: Դրանց օգտագործման համար մոդուլը պետք է կամ իրականացնի routing.yml ֆայլ, կամ օգտագործի route_provider handler-ը անոտացիայում:

Հղումներ և երթուղիչի մատակարար

Վերը նշված հղումները՝ միասին «route_provider»-ի հետ, ապահովում են հետևյալ երթուղիների հասանելիությունը Drupal-ում:

Հղումների օգտագործում
Այս հղումներն հասանելի են entity օբյեկտի toUrl() մեթոդի միջոցով՝

$view_url_object = $entity->toUrl();  // Դեֆոլտը 'canonical'-ն է
$edit_url_string = $entity->toUrl('edit-form')->toString();

Հղումներ՝

• Entity API - Ավտոգեներացված փաստաթուղթ
• Հատուկ բովանդակային օբյեկտ ստեղծում - Շատ պարզ օրինակ
• Entity տիպի ստեղծում Drupal 8-ում - Խորքային օրինակ հանդիպակներով, թույլտվություններով, երթուղիներով և հղումներով
• Կոնֆիգուրացիոն օբյեկտի տիպի ստեղծում Drupal 8-ում - Խորքային օրինակ հանդիպակներով, երթուղիներով և սխեմայով
• [Արտաքին] Entity Type Walkthrough - Ընդհանուր entity տիպի գործնական փաստաթուղթ