Add stream wrappers to access extension files

Problem/Motivation

Starting from #2351919: Replace uses of drupal_get_path() with __DIR__ where possible → , when the PHP code needs to include or parse files inside the module or theme directory space, will simply use _DIR_ instead of drupal_get_path(). This is sufficient, intuitive and more performant than calling drupal_get_path().

However, drupal_get_path() is widely used to refer files (.js, .css, images, assets) outside a module or theme. This isn't very intuitive for new developers. Stream wrappers make much more sense and simplify the API for developers trying to refer directories or files from outside the current extension in code.

Proposed resolution

Introduce extension stream wrappers:

Examples

Profile: profile://

Assuming the standard profile is installed:

• Referring a directory:
  • Actual: drupal_get_path('profile', 'standard') . '/config'
  • Proposed: profile://config
  • Path: core/profiles/standard/config
• Referring a file:
  • Actual: drupal_get_path('profile', 'standard') . '/config/install/automated_cron.settings.yml'
  • Proposed: profile://config/install/automated_cron.settings.yml
  • Path: core/profiles/standard/config/install/automated_cron.settings.yml

Module: module://

Assuming the node module is enabled but color module is not:

• Referring a directory:
  • Actual: drupal_get_path('module', 'node') . '/config'
  • Proposed: module://node/config
  • Path: core/modules/node/config
• Referring a file:
  • Actual: drupal_get_path('module', 'node') . '/config/install/node.settings.yml'
  • Proposed: module://node/config/install/node.settings.yml
  • Path: core/modules/node/config/install/node.settings.yml
• Referring a resource in a uninstalled or inexistent module:
  • Actual: drupal_get_path('module', 'color') . '/config'
  • Proposed: module://color/config
  • Path: Throws \RuntimeException

Theme: theme://

Assuming the bartik theme is installed but seven theme is not:

• Referring a directory
  • Actual: drupal_get_path('theme', 'bartik') . '/config'
  • Proposed: theme://bartik/config
  • Path: core/themes/bartik/config
• Referring a file
  • Actual: drupal_get_path('theme', 'bartik') . '/color/color.inc'
  • Proposed: theme://bartik/color/color.inc
  • Path: core/themes/bartik/color/color.inc
• Referring a resource in a uninstalled or inexistent theme:
  • Actual: drupal_get_path('theme', 'seven') . '/config'
  • Proposed: theme://seven/config
  • Path: Throws \RuntimeException

Remaining tasks

1. Profiling to compare performance of the new code with the old.

API changes

New abstract class for extensions stream wrappers:

• \Drupal\Core\StreamWrapper\ExtensionStreamBase

New stream wrapper classes:

• \Drupal\Core\StreamWrapper\ModuleStream
• \Drupal\Core\StreamWrapper\ThemeStream
• \Drupal\Core\StreamWrapper\ProfileStream

Data model changes

None.