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
- 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.