What Drupal 8 API changes are still outstanding?

xjm's picture

Completing Drupal 8's core APIs is a key step toward releasing Drupal 8. During this phase of Drupal 8's development, we restrict API changes to only those that are necessary to resolve important issues, and API changes must go through an approval process. Since the announcement of the beginning of the API freeze on July 1st, we've made substantial progress defining the state of our APIs. 128 major and critical issues have been fixed, and core maintainers have reviewed and approved outstanding API changes in more than 50 open Drupal core issues, with additional changes under review.

This post details the most important outstanding API changes for core and contributed module developers (APIs that will change between the current 8.x HEAD and the release of 8.0). It does not include all changes, and other important changes might still be added.

Routing and menus

All form and page callbacks are being converted to the new routing system. The procedural versions of these callbacks will be removed from the core codebase, and before Drupal 8.0 is released, hook_menu() will no longer work to register callbacks. Use the new routing system instead. (Make particular note of the ControllerBase and FormBase classes for simple form and page callbacks.)

The Drupal 7 Ajax API will also be removed, so Ajax commands should also be converted to the new routing system and use the new Drupal 8 Ajax API.

There are numerous other outstanding issues with routing, menus, and links that may require additional API changes, so be aware that code using these systems might require additional updates before 8.0 is released.

Configuration variables

All configuration variables are being converted to the Drupal 8 configuration system (or, in some cases, the state system). variable_get(), variable_set(), and variable_delete() will be removed before Drupal 8.0 is released. Use the Configuration system instead when a configuration variable could be deployed between sites, or the state system when a variable is a site-specific flag (for example, the last time that cron was run).

Entity Field API

The Entity Field API has been mostly rewritten for Drupal 8, but not all of the legacy Drupal 7 entity and field APIs have been removed, and the Drupal 8 API is still being refined:

If you make use of entities or fields in your code, you can test out these critical APIs and provide feedback while they are still being finalized, but you should expect many additional changes before Drupal 8.0 is released.

The disabled module status is being removed

To ensure module data integrity and resolve numerous critical issues, the disabled module status is being removed. By the time 8.0 is released, it will no longer be possible to disable a module without uninstalling it. Any logic associated with the disabling of modules should be moved to uninstallation.

drupal_set_title(), drupal_set_breadcrumb(), and similar functions will be removed

To allow better render caching in Drupal core, drupal_set_title() is being removed. Set the page title by adding a _title to your route definition, or add a #title element to your page's render array if you need a dynamic title. (See drupal_set_title() replaced by returning the title in the render array for more details.)

drupal_set_breadcrumb() is also being removed. Use the new breadcrumb system instead.

drupal_add_css() and drupal_add_js() will be removed

To improve Drupal's asset management and support better render caching, drupal_add_css() and drupal_add_js() are being removed. Use the #attached property on the element's render array instead.

The global $user is deprecated

The global $user variable is no longer supported, and its use will be removed throughout Drupal core before 8.0 is released. While the variable will be retained for certain low-level internals, core and contributed modules should instead use the current user service.

Core listings are being converted to Views

Core content listing pages, blocks, and administrative screens are being converted to views now that the Views module is a part of Drupal core. Therefore, legacy procedural code related to these listings will still be removed, as well as one-off page controllers and block plugins related to these listings.

Comments are being converted to a field

To allow comments on any entity type, comments are being converted to a configurable field. Modules extending the comment module will need significant changes following this patch.

Other changes

The list of changes above is not comprehensive. Numerous other, less impactful API changes have been approved, and other API changes will also be approved as additional issues are addressed. (See more on the process for approving API changes during the API completion phase.)

Note also that numerous functions in the Drupal 8 codebase have been marked @deprecated (including many of those listed above). In general, you should replace calls to deprecated functions with the alternative specified in the function's API documentation.

For a list of the API changes that have already been made in Drupal 8, see the Change records for Drupal core. Note that many change records are still outstanding. You can help other developers by contributing to this much-needed API change documentation.