Things I learned so I know slightly better what I do not know 🤓

can be used for anything!

We have gotten better! 🥳

Backwards compatibility

dri.es/making-drupal-upgrades-easy-forever

Evolvability

Maintainability

d.o/core/d8-bc-policy: @api vs @internal

But in Drupal core…

@api

0 occurrences

@internal

53 occurrences

99% "undocumented"
⇒ 99% considered API

Two years later:

1. More code considered "internal APIs" and 53 711 @internal occurrences

2. For public APIs, the deprecation process is a is a requirement; for internal APIs, we provide BC and deprecation where possible, but might make breaking changes in situations where BC is not possible or has negative consequences.

@deprecated

404

Two years later:

Current best practice?

API providers

1. Don't break existing callers.
2. Notify existing callers of changed code.

/**
 * Sets a message to display to the user.
…
 * @deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
 *   Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead.
 */
function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) {
  @trigger_error('drupal_set_message() is deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead. See https://www.drupal.org/node/2774931', E_USER_DEPRECATED);
  $messenger = \Drupal::messenger();
  if (isset($message)) {
    $messenger->addMessage($message, $type, $repeat);
  }
  return $messenger->all();
}

API consumers

1. Get notified of deprecations in automated testing:

         run_tests.phpunit:
           types: 'PHPUnit-Unit'
           testgroups: '--all'
           suppress-deprecations: false # 🥳
           halt-on-fail: false

2. Update existing callers retaining BC:

       if (\Drupal::hasService('messenger')) {
         \Drupal::messenger()->addMessage(…);
       }
       else {
         drupal_set_message(…);
       }

#3024461: Consistent deprecation messages format
⬇

Overengineered

Q: Why does Drupal have so many APIs?
A: Optimized for targeted overrides
    ⇒ granular APIs
    ⇒ many, many APIs

• forest ~ Drupal
• tree ~ Drupal component
• branch ~ Drupal component feature
• leaf ~ Drupal component feature method

Drupal allows you to replace a particular leaf.
Others require replacing a branch or even a tree.

Drupal has 3 types of APIs

Explicit APIs

hooks, plugin types, tagged services

Implicit APIs

markup structure, render array structure, call order (weights, priorities)

Accidental APIs

many (most?) interfaces (and even classes!)

The API assumption

• Drupal: X is API
• Others: X is NOT an API

Underengineered

Part 1: Accidental API

1. D8: OOPify everything
2. Every class must have an interface
3. Interfaces coupled to the sole implementation
4. BC broken by bugfixes & new implementations

- Clients don't see any benefit in spending money on a complete re-platforming - the changes are too big to be considered just an "upgrade"
- All levels of developer are finding D8 incomprehensible because the API surface is too large, with too many options and missing/poor docs

— Sally Young (@justafish) April 3, 2019

Example

Issue #2266809: Make QuickEditEntityFieldAccessCheck::access() use the $account that's passed in

    * @param string $field_name
    *   The field name.
+   * @param \Drupal\Core\Session\AccountInterface $account
+   *   The user for which to check access.
    *
    * @return \Drupal\Core\Access\AccessResultInterface
    *   The access result.
    */
-  public fn accessEditEntityField($entity, $field_name);
+  public fn accessEditEntityField($entity, $field_name, AccountInterface $account);

 }

(Introduced by yours truly in #1824500: In-place editing for Fields on Dec 21, 2012.
Suffering the consequences many years later.)

Poorly designed APIs make BC very difficult

API support cost

Prefer duplication over the wrong abstraction

API when:

1. data to prove soundness of API design
2. sufficient demand

API discoverability & complexity

Little work + high complexity (granular APIs)

vs

More work + low complexity (duplication)

Underengineered

Part 2: orthogonality

API dependencies

• Automated Cron: 5 (Form + Config + EventSub + Cron + State)
• BigPipe: 5 (Render + AJAX + Cache + EventSub + Req/Resp)
• Entity API uses >10 APIs

⇒ using Entity API === using >10 APIs!

API cascades

NodeInterface $node

1. NodeInterface extends ContentEntityInterface, EntityChangedInterface, EntityOwnerInterface, RevisionLogInterface, EntityPublishedInterface
2. ContentEntityInterface extends \Traversable, FieldableEntityInterface, RevisionableInterface, TranslatableInterface
3. FieldableEntityInterface extends EntityInterface
4. EntityInterface extends AccessibleInterface, CacheableDependencyInterface, RefinableCacheableDependencyInterface

FieldableEntityInterface::get() aka $node->get($field_name)

1. FieldItemListInterface extends ListInterface, AccessibleInterface
2. ListInterface extends TraversableTypedDataInterface, \ArrayAccess, \Countable
3. TraversableTypedDataInterface extends TypedDataInterface, \Traversable
4. TypedDataInterface

Massive composition & long inheritance chains require massive knowledge

Underengineered

Part 3: assumptions

1. Drupal core does X
2. Module/API Foo assumes X
3. Install contrib module Bar: X ⇒ Y
4. 😭

Breaks when advagg is installed 😭

     $request = $this->requestStack->getCurrentRequest();
     $link_headers = $request->attributes->get('http2_server_push_link_headers', []);
     foreach ($elements as &$element) {
+      if (!static::isLinkRelStylesheet($element)) {
+        continue;
+      }
+
       // Locally served CSS files that are sent to all browsers can be pushed.
-      if ($element['#tag'] === 'link' && $element['#browsers']['!IE'] === TRUE && $element['#browsers']['IE'] === TRUE && $element['#attributes']['href'][0] === '/' && $element['#attributes']['href'][1] !== '/') {
+      if (isset($element['#attributes']['href']) && static::hasRootRelativeUrl($element, 'href') && static::isUnconditional($element)) {
         $link_header_value = '<' . $element['#attributes']['href'] . '>; rel=preload; as=style';
         $link_headers[] = $link_header_value;

Make assumptions explicit

even better:

Test assumptions

Functionality-only modules

BigPipe + Dynamic Page Cache

Try hard to not provide an API

(Then BC is kept as long as functionality works!)