In the light of #1845546: Implement validation for the TypedData API, #1867856: Use annotation discovery for data type plugins and #1838676-17: Support dynamic entity type management I think we should try to bring the TypedData API closer to plain PHP's built in type system. More concrete, I think we should exploit PHP classes as *the* representation for our data types.

Suggestions:

  • Embrace CamelCase naming for the plugin IDs and make them inline with the actual class names without namespaces. (If required for namespacing, prefix the class name with the module name.) This helps to change the mental model such that the class and the type becomes the same. For example, let's have type => 'DateItem' instead of type => 'date_item'. Thus, when one reads the typed data definition including type => DateItem, it suddenly becomes clear that it's gonna be an instance of the DateItem class.
    I think we should keep the namespace out of the name though, such that the type doesn't become to verbose and it's still clear that it refers to the plugin, not the concrete class (you can specify another class using the 'class' key, or we might want to do derivatives!) Also, the actually used class could be a different one anyway as people could alter the plugin definition to swap things out.
    This suggestion would be inline with current approach of #1845546: Implement validation for the TypedData API, which does the same for referring to validation constraint plugins.
  • Declare class properties for all complex data types as we already do for entities, e.g. add properties for all field type values (e.g. add public $value;, public $format;)
  • Change the @var doxygen to actually point to the really used implementation class. That way it's much easier to follow what class gets instantiated where. Maybe even embrace the IntegerItem[] notation for fields (=lists of field items).

Thus, as a first step I'd suggest doing that, but do not enforce a 1:1 type-class relationship for now, as e.g. it might be useful to have derivatives for types e.g. to expose entity types or entity bundles that way. If we end up requiring a class per entity type and did not run into other derivative use cases, it might help simplifying things here as well - but we can re-visit this question later on.

Advantages:

  • Improved DX - it's easier to understand the control flow.
  • With registered class properties we potentially gain autocompletion in IDEs for built-in fields. (Depending on the notation we embrace for fields). It also opens the door for using annotations as the source for the property definitions (whether we want that is its own discussion).
  • At a point, I think we'll need to introduce type inheritance to the system, e.g. for parameter type matching of #1846172: Replace the actions API or blocks. Instead of re-inventing that in PHP we could mostely just rely on the class hierarchy. (I think it would need some support for interfaces also, but that should work out.)
  • Suddenly stuff like writing a serializer/normalizer for data types becomes simpler as you can rely on the class. See http://drupal.org/node/1838676#comment-6806628.

Comments

fago’s picture

Title: Bring the TypedData API closer to plain PHP » Bring data type plugins closer to their PHP classes

improving title

tim.plunkett’s picture

Category: task » feature

This would certainly be nice to have, but it's not really a blocker.

fago’s picture

Category: feature » task
Priority: Major » Normal

true. I guess it should be a normal task. This relates to #2002102: Move TypedData primitive types to interfaces

fago’s picture

Component: base system » typed data system
Issue tags: +Typed sanity

tagging

fago’s picture

Issue tags: -Typed sanity

Since we have #2028097: Map data types to interfaces to make typed data discoverable now, I think this is mostly obsolete. Leaving open for the doc improvements though.

fago’s picture

Issue summary: View changes

Updated issue summary.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

fago’s picture

Status: Active » Closed (outdated)
Declare class properties for all complex data types as we already do for entities, e.g. add properties for all field type values (e.g. add public $value;, public $format;)
Change the @var doxygen to actually point to the really used implementation class. That way it's much easier to follow what class gets instantiated where. Maybe even embrace the IntegerItem[] notation for fields (=lists of field items).

This changed for entities meanwhile and thus is outdated (except config entities).

Also, changes like this ore camel-cased plugin names are out of scope to change now in d8. This would be a do topic, but I do not think there is anything of value here to keep. -> obsolete.