Entity API-ն իրականացնում է Typed Data API-ն

Համարժեք բարելավում

• Entity API-ն այժմ իրականացնում է Typed Data API-ն։

Այս նոր իրականացման մեջ Entity API-ի ամեն ինչ ներկայացված է դաշտի տեսքով, որը հիմնված է նույն API-ի վրա, այդ պատճառով էլ էնտիթիները կանխատեսելի և համակողմանի են։

Drupal-ի տվյալների մոդելի հասկացում

Առաջինը, նախքան խորը ուսումնասիրենք Typed Data API-ն, պետք է հասկանանք, թե ինչպես է նախկինում ընկալվում Drupal-ի տվյալների մոդելը (Entity API)։ Սա կարևոր է, քանի որ հենց այստեղից է առաջացել Typed Data API-ն, իսկ Entity API-ն հանդիսանում է այն համակարգերից մեկը, որոնց համար այն մշակվել է։

Էնտիթին մեկ բարդ տվյալների մասը է, որը բաղկացած է այլ տվյալների մասերից, ինչպիսիք են դաշտերը՝ էլեմենտների ցանկով։ Դաշտի էլեմենտն էլ բարդ է՝ բաղկացած է ավելի փոքր տվյալների կտորներից, օրինակ՝ տեքստային արժեք և մուտքի ֆորմատ։ Սակայն բարդությունը հասնում է այնպիսի մակարդակի, որ ինչ-որ բան կարելի է նկարագրել որպես պարզ տիպի տվյալ, օրինակ՝ տող կամ ամբողջ թիվ։

Պարզեցված օրինակ Drupal 7-ից (լեզվի կոդ չկա, քանի որ Drupal 8-ը դա այլ կերպ է անում)

Օրինակ 1

// Էնտիթիները բարդ են, պարունակում են այլ տվյալների կտորներ։
$entity;

// Դաշտերը բարդ չեն, դրանք պարունակում են միայն էլեմենտների ցանկ։
$entity->image;

// Էլեմենտները բարդ են, պարունակում են այլ տվյալների կտորներ, թարգմանելի են և հասանելի (ունեն թույլտվություններ)։
$entity->image[0];

// Ֆայլի ID-ն պարզ ամբողջ թիվ է։
$entity->image[0]['fid'];

// Alternative տեքստը պարզ տող է։
$entity->image[0]['alt'];

Ամբողջացնում ենք միասին

Ստորև ներկայացված է պարզեցված օրինակ, թե ինչպես է Entity API-ն իրականացնում ինտերֆեյսները, բացի Typed Data API-ից։ Իրականում Entity API-ն ընդլայնում է այդ ինտերֆեյսները՝ ավելացնելով լրացուցիչ մեթոդներ, որոնք անհրաժեշտ են Entity API-ին։ Այնուամենայնիվ, ստորև նշված բոլոր հայտարարությունները ճշմարիտ են․

Օրինակ 2

// Էնտիթիները բարդ են։
$entity instanceof ComplexDataInterface;

// Հատկությունները բարդ չեն, դրանք միայն էլեմենտների ցանկ են։
$entity->get('image') instanceof ListInterface;

// Էլեմենտները բարդ են։
$entity->get('image')->offsetGet(0) instanceof ComplexDataInterface;

// Typed Data օբյեկտը, որը ներկայացնում է alt արժեքը։
$entity->get('image')->offsetGet(0)->get('alt') instanceof TypedDataInterface;

// alt արժեքը պարզ տող է։
is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

Ստորև ամփոփվում է, թե ինչպես է Entity API-ն ընդլայնում Typed Data API-ն՝ որոշ լրացուցիչ պահանջների համար․

Օրինակ 3

interface EntityInterface extends ComplexDataInterface, TranslatableInterface, AccessibleInterface {
 // ...
}

interface FielditemListInterface extends ListInterface {
 // ...
}

// Ուշադրություն դարձրեք, որ սա ընդլայնում է երկու ինտերֆեյս։ Ներքևում բացատրություն կա։
interface FieldItemInterface extends ComplexDataInterface, TypedDataInterface {
 // ...
}

// Ստորև ներկայացված են իրական իրականացումներ։

// Ստացած է մի абստրակտ դաս, որն ունի ընդհանուր լոգիկա։
class ImageItem extends FieldItemBase {
 // ...
}

// Ստացած է մի абստրակտ դաս, որն ունի ընդհանուր լոգիկա։
class String extends TypedData {
 // ...
}

[Հաջորդ երկու պարբերակները պահանջում են լրացուցիչ աշխատանք]

Երկու ամենանշանակալիները վերևում՝

1. EntityInterface-ն ընդլայնում է որոշ ծառայողական ինտերֆեյսներ, ինչպիսիք են թարգմանությունն ու մուտքի թույլտվությունները։ Դա պետք է բավականին պարզ լինի։
2. FieldItemInterface-ը ընդլայնում է ինչպես ComplexDataInterface-ը, այնպես էլ TypedDataInterface-ը։ Ինչպես նշվել է, էլեմենտները բարդ են, քանի որ պարունակում են ավելի փոքր տվյալների կտորներ (օրինակ՝ տեքստային արժեք և ձևաչափ)։ Բայց միևնույն ժամանակ էլեմենտը ինքնին նաև Typed Data-ի մաս է, ուստի ունի իր սեփական սահմանումը և տիպը։

Այսպիսով, ամփոփելով՝ ի լրումն Օրինակ 2-ի, ստորև նշված բոլոր հայտարարությունները նույնպես ճշմարիտ են․

Օրինակ 4

$entity instanceof EntityInterface;

$entity->get('image') instanceof FieldItemListInterface;

$entity->get('image')->offsetGet(0) instanceof FieldItemInterface;

$entity->get('image')->offsetGet(0)->get('alt') instanceof String;

is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

API-ի օգտագործում

[Այս բաժնում պետք են լրացուցիչ օրինակներ]

Entity API-ն սահմանում է որոշ կախարդական մեթոդներ, ինչպիսիք են __get(), որպեսզի ապահովի դաշտի արժեքներին արագ և հեշտ մուտք։ Այսպիսով, API-ի օգտագործումը շատ պարզ է, և շարադրանքը նման է Drupal 8-ից առաջվա ժամանակներին։

Ներքևում ներկայացված է՝ ինչպես կարելի է ստանալ պատկերին առընթեր alternative տեքստի իրական արժեքը՝

Օրինակ 5

// Ամենաամբողջական ձևը։
$string = $entity->get('image')->offsetGet(0)->get('alt')->getValue();

// Entity API-ի հավելված կախարդանքով։
$string = $entity->image[0]->alt;

// Entity API-ի ավելի շատ կախարդանքով, որը վերցնում է առաջին էլեմենտը
// լռելյայն ցուցակից։
$string = $entity->image->alt;

Վերևի օրինակն ավելացնում է միայն հարմար շարադրանք հին API-ին։ Ստորև ներկայացված օրինակները ցույց են տալիս, թե որտեղ է այս API-ի իրական արժեքը՝ տվյալների ստուգումն է․

Օրինակ 6

// Վերադարձնում է դաշտերի անուններով զանգված բոլոր դաշտերի և նրանց սահմանումների համար։ Օրինակ՝ ‘image’ դաշտը։
$property_definitions = $entity->getFieldDefinitions();

// Վերադարձնում է հատկությունների անուններով զանգված, օրինակ՝ ‘file_id’ և ‘alt’ հատկությունների համար։
$property_definitions = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinitions();

// Վերադարձնում է միայն ‘alt’ property's սահմանումը։
$string_definition = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinition('alt');

Վերոնշյալ սահմանումների հիման վրա այժմ կարող ենք կատարել խելացի գործողություններ, ինչպիսիք են սերիալիզացիան կամ տվյալների այլ զանգվածի պատրաստումը։ Մենք նաև կարող ենք տրամադրել այդ տվյալները սեմանտիկորեն հարուստ API-ներով, ինչպես JSON-LD endpoint-ը, որպեսզի այլ համակարգերը հասկանան մեր տվյալների հիմքերը։

Տեսեք Https://drupal.org/node/2078241 լրացուցիչ տեղեկությունների և օրինակների համար՝ թե ինչպես սահմանել և օգտագործել էնտիթի դաշտերի սահմանումները։