mglaman / drupal-typed-data-by-example

Drupal's Typed Data API by example

Drupal's Typed Data API by example

This repository aims to help show use cases and various exercises with using Drupal's Typed Data API.

The Typed Data API was created to provide developers with a consistent way of interacting with data in different ways.

Purpose

This repository provides examples of using the Typed Data API. The examples range from generic usage explaining the different data types available, to creating complex data definitions, to utilizing them in real world Drupal applications.

The intent is not to run this code in your Drupal site, but to browse the code examples.

Structure

The examples are broken into different groups, each with their own directory:

• primitives: each example covers the data types provided by Drupal core. These are intended to be simplistic examples of using a value and wrapping it in Typed Data data types for validation and representation.
• lists: each example covers using lists (arrays of a specific type)
• maps: each example covers using the Map data type, which allows you to define complex data definitions to describe an object's shape.
• serialization: each example shows how the Typed Data API integrates with Drupal's Serialization module, which leverages the Serializer component from Symfony.

Trying it out!

All of the examples can be run to see sample outputs.

First, install the dependencies and generate the autoloader (requires PHP ^8.0):

composer install

For example, the following will run the emails example in primitives/ and print any of the additional output provided for context.

php primitives/email.php

drupal-typed-data-by-example's Issues

Add documentation better explaining primitive data types

Write better words about primitive data types and getCastedValue

Float example

Examples using the float data type

Rename "strings" directory

The strings directory should contain more basic data types, and I cannot think of a better name.

It's probably best to rename it to primitives and handle examples of all data types that implement \Drupal\Core\TypedData\PrimitiveInterface.

That covers

• integers
• timestamps
• time span (seconds, integer)
• float
• binary (resource)
• string (plain)
• email
• datetime
• uri
• boolean

Explain how TypeData can satisfy a Data Sync story

Stop me if you've heard this before.

I have products in my Drupal site, and products in another (maybe not Drupal) site. I want to run a process and sync the product data. Over time, I've learned that you can't just fire and forget that process. There is a strong need to have a series of reports that shows data that isn't properly synced, as well as vigorously report on any issues with the sync so we can fix whatever issue is leading to the data not syncing well. So that's the use case.

When creating data sync reports it's important to answer the following questions:

• Is there any data in datasource A that is not in datasource B?
• Is there any data in datasource B that is not in datasource A?
• When I do an operation (create/update/disable/delete), I need to record detailed error messages / validation errors (from either side/source) if anything goes wrong so I can figure out how to correct it.

and maybe I could optimize performance by doing these checks during the process:

• Create/Update logic, Does my product in datasource A exist in datasource B?
• Skip Update logic, Is my product in datasource A have any updates for the product in datasource B?

There are many programmatic approaches to solving the above questions. It would be nice to see a solution that used TypeData. I am imagining a solution that takes data from each datasource and converts them into a common data type so that:

• direct comparisons can be easier
• the size of the intermediate state could be much smaller that a fully hydrated node
• ultimately be less code because of inherited getters/setters
• maybe easier to write code that handles validation of individual properties.

If you've got something like this already thought through, I'd say run with that. If not, I'm eager to help write some documentation on how to do this...as soon as I figure it out.

Boolean example

Examples using the boolean data type

Timestamp examples

Examples using the timestamp data type

Binary data example

Examples using the binary data type

Datetime ISO8601 example

Examples using the datetime_iso8601 data type

DataReferenceInterface examples

It'd be nice to see if this is possible to provide examples for. Drupal core only has \Drupal\Core\TypedData\Plugin\DataType\LanguageReference and \Drupal\Core\Entity\Plugin\DataType\EntityReference as examples.

Duration (ISO8601) example

Examples using the duration_iso8601 data type

URI example

Examples using the uri data type

Integer examples

Examples using the integer data type

Document methods on the typed data manager

The typed data manager has a few create methods and it can be confusing.

Do I need create or do I need createInstance or createFromDataType

Not to mention all of the other plugin manager methods.

Automatic Typed Data Plugin Discovery

The drupal.org documentation (as well as the code from other core modules) suggests that Typed Data Definitions can be discovered by the Typed Data Manager when a module is loaded, simply by:

1. Creating a class that extends Drupal\Core\TypedData\TypedData or one of its subclasses
2. Creating a class that extends Drupal\Core\TypedData\DataDefinition or one of its subclasses.
   1. Overriding getPropertyDefinitions method and creating the data definitions or property definitions within.
3. Attaching a @DataType{ ... } annotation to the first class.
   1. Setting the definition_class attribute of the annotation to the fully qualified name of the second class
   2. Putting a machine name in the id attribute of the annotation
4. Saving both classes in php files in the src/Plugin/DataType directory of a custom module.

However, despite my best attempts (including reloading cache and registry, and reinstalling module) it appears the Typed Data Manager hasn't discovered my custom data type automatically. Attempting to use Serialization API to deserialize some csv data into an object of the custom data type simply produces the expected error:

Drupal\Component\Plugin\Exception\PluginNotFoundException: The "Drupal\<module_name>\Plugin\DataType\<ClassName>" plugin does not exist.

I would appreciate if an example better than what drupal.org provides could be made.

Time span example

Examples using the timespan data type