Entity API Typed Data API को लागू करता है

महत्वपूर्ण सुधार

• Entity API अब Typed Data API को लागू करता है

इस नए कार्यान्वयन में Entity API की हर चीज़ एक ही API पर आधारित field है, इसलिए entities पूर्वानुमानित और संगत होती हैं।

Drupal डेटा मॉडल को समझना

सबसे पहले, Typed Data API में गहराई से जाने से पहले, हमें यह समझना होगा कि पहले Drupal (Entity API) के डेटा मॉडल को कैसे देखा जाता था। यह महत्वपूर्ण है, क्योंकि Typed Data API यहीं से आता है, और Entity API उन प्रणालियों में से एक है, जिनके लिए इसे डिज़ाइन किया गया था।

Entity एक जटिल डेटा का हिस्सा है, जिसमें अन्य डेटा भाग होते हैं, जैसे items की सूची वाले fields। Field item भी जटिल है—यह और अधिक डेटा टुकड़ों से बना है, जैसे कि एक टेक्स्ट मान और एक input format। हालांकि, यह जटिलता इतनी दूर तक जाती है कि कुछ चीज़ों को primitive data type के रूप में वर्णित किया जा सकता है, जैसे string या integer।

Drupal 7 से एक सरल उदाहरण (भाषा कुंजी के बिना उदाहरण, क्योंकि Drupal 8 इसे अलग तरीके से संभालता है):

उदाहरण 1

// Entities जटिल हैं, वे अन्य डेटा टुकड़े रखते हैं।
$entity;

// Fields जटिल नहीं हैं, वे केवल items की एक सूची रखते हैं।
$entity->image;

// Items जटिल हैं, वे अन्य डेटा टुकड़े रखते हैं। वे translatable और accessible (permissions होते हैं) भी हैं।
$entity->image[0];

// File ID एक primitive integer है।
$entity->image[0][‘fid’];

// Alternative text एक primitive string है।
$entity->image[0][‘alt’];

सभी को एक साथ लाना

नीचे एक सरल उदाहरण है कि Entity API कैसे Typed Data API से अलग interfaces को लागू करता है। वास्तव में, Entity API इन interfaces का विस्तार करता है, अतिरिक्त methods जोड़ते हुए जो Entity API के लिए आवश्यक हैं। फिर भी, नीचे दिए गए सभी कथन true के रूप में मूल्यांकित होते हैं:

उदाहरण 2

// Entities जटिल हैं।
$entity instanceof ComplexDataInterface;

// Properties जटिल नहीं हैं, वे केवल items की सूची हैं।
$entity->get('image') instanceof ListInterface;

// Items जटिल हैं।
$entity->get('image')->offsetGet(0) instanceof ComplexDataInterface;

// Alt मान का प्रतिनिधित्व करने वाला typed data object।
$entity->get('image')->offsetGet(0)->get('alt') instanceof TypedDataInterface;

// Alt मान एक primitive string है।
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 {
 // ...
}

// ध्यान दें कि यह दो interfaces का विस्तार करता है। नीचे व्याख्या।
interface FieldItemInterface extends ComplexDataInterface, TypedDataInterface {
 // ...
}

// नीचे कुछ वास्तविक implementations आते हैं।

// कुछ common logic के साथ एक abstract class का विस्तार करता है।
class ImageItem extends FieldItemBase {
 // ...
}

// कुछ common logic के साथ एक abstract class का विस्तार करता है।
class String extends TypedData {
 // ...
}

[निम्नलिखित दो अनुच्छेदों को और काम की ज़रूरत है]

ऊपर की दो सबसे उल्लेखनीय बातें:

1. EntityInterface अनुवाद और एक्सेस क्षमताओं जैसी चीज़ों के लिए कुछ उपयोगिता interfaces का विस्तार करता है। यह काफी स्पष्ट होना चाहिए।
2. FieldItemInterface ComplexDataInterface और TypedDataInterface दोनों का विस्तार करता है। जैसा कि पहले बताया गया है, items जटिल हैं क्योंकि वे अधिक डेटा टुकड़े रखते हैं (जैसे text value और text items के लिए format)। लेकिन साथ ही, item स्वयं typed data का हिस्सा है, इसलिए इसका अपना definition और data type होता है।

इसलिए, संक्षेप में, उदाहरण 2 के अतिरिक्त, नीचे दिए गए सभी कथन भी true हैं:

उदाहरण 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 कुछ magic methods परिभाषित करता है, जैसे __get(), ताकि field मानों तक तेज़ और आसान पहुँच सुनिश्चित की जा सके। इस प्रकार, API का उपयोग करना बहुत सरल है, और इसका syntax Drupal 8 से पहले के युग जैसा दिखता है।

Image के alternative text का वास्तविक मान प्राप्त करना इस प्रकार किया जाएगा:

उदाहरण 5

// सबसे विस्तृत तरीका।
$string = $entity->get('image')->offsetGet(0)->get('alt')->getValue();

// Entity API द्वारा जोड़े गए magic के साथ।
$string = $entity->image[0]->alt;

// Entity API द्वारा जोड़े गए और magic के साथ, डिफ़ॉल्ट रूप से सूची में पहला item प्राप्त करने के लिए।
$string = $entity->image->alt;

ऊपर का उदाहरण केवल पुराने API में अच्छा syntax जोड़ता है। नीचे के उदाहरण दिखाते हैं कि इस API का वास्तविक मूल्य कहाँ प्रकट होता है—डेटा validation:

उदाहरण 6

// सभी fields और उनके definitions के लिए named keys वाला array लौटाता है।
// उदाहरण के लिए ‘image’ field।
$property_definitions = $entity->getFieldDefinitions();

// सभी properties और उनके definitions के लिए name keys वाला array लौटाता है।
// उदाहरण के लिए ‘file_id’ और ‘alt’ properties।
$property_definitions = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinitions();

// केवल ‘alt’ property का definition लौटाता है।
$string_definition = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinition('alt');

ऊपर दिए गए definitions के आधार पर हम अब स्मार्ट चीजें कर सकते हैं, जैसे serialization या किसी अन्य डेटा array में बदलना। हम इन डेटा को semantic रूप से समृद्ध API जैसे JSON-LD endpoint के माध्यम से भी उपलब्ध करा सकते हैं, ताकि अन्य प्रणालियाँ हमारे डेटा की मूल बातें समझ सकें।

अधिक जानकारी के लिए देखें https://drupal.org/node/2078241, कि entity field definitions को कैसे परिभाषित और उपयोग करें।