Add leading underscore and other discouragement to drupal_add_css() and drupal_add_js()

and other discouragement

Lovely title :)

This would also be a simple patch to write, so tagging novice. :)

Let's do this before more people continue using them.

Added the leading underscore to both functions and usages.
Both were already deprecated and documented the use of #attached.

Tests are calling these functions directly, which seems fine for now, no? They'll need underscores. We'll probably eventually want methods on WebTestBase to add CSS and JS for tests.

call_user_func('drupal_add_css', 'core/themes/stark/css/layout.css', Array)

Ah! A little string magic that might have escaped a regex search in drupal_process_attached.

// Add both the JavaScript and the CSS.
// The parameters for _drupal_add_js() and _drupal_add_css() require special
// handling.
foreach (array('js', 'css') as $type) {
  foreach ($elements['#attached'][$type] as $data => $options) {
    // If the value is not an array, it's a filename and passed as first
    // (and only) argument.
    if (!is_array($options)) {
      $data = $options;
      $options = NULL;
    }
    // In some cases, the first parameter ($data) is an array. Arrays can't be
    // passed as keys in PHP, so we have to get $data from the value array.
    if (is_numeric($data)) {
      $data = $options['data'];
      unset($options['data']);
    }
    call_user_func('drupal_add_' . $type, $data, $options);
  }
  unset($elements['#attached'][$type]);
}

I found a few more with this regex:

[^_\$]drupal_add_(js|css|')+

Go bot, go.

Minor:

+++ b/core/lib/Drupal/Core/Ajax/AjaxResponse.php
@@ -158,7 +158,7 @@ protected function ajaxRender(Request $request) {
+      // @see _drupal_add_js
...
-      // @see drupal_add_js

Since this is already being changed, can we add the () ?

Actually since #11 is very minor, and I couldn't find anything to complain and it passes tests: marking RTBC.

Fixed #11.

The patch at #13 mangled with file permissions of default.settings.php, sorry.

Still RTBC. ++

Awesome!

This changes stuff in quite a few files, but I just checked manually and it doesn't conflict with any RTBC criticals. (Wasn't able to check the majors, though.)

I was also surprised to see we have absolutely no change notification from any of the previous issues warning that these functions are deprecated (only change notices talking about their new features, which should also be updated accordingly), so let's please get on that as soon as possible so that the message gets heard loud and clear by contrib maintainers and we don't undo the awesome effort that was done here.

Committed and pushed to 8.x. Thanks!

I'm going to write the API change notification!

Proposed Change Notice.

Summary

• Add leading underscore to the deprecated drupal_add_css() and drupal_add_js() functions to make it private and update the docs to make it clear no code should call it.
• This will break the existing usage and force people to use #attached.

Before

drupal_add_css()
drupal_add_js()

After

_drupal_add_css()
_drupal_add_js()

Hm. While that would work for your average issue needing a change notice, I think for this one we need to be more explicit than that. It should be something more along the lines of:

---

Title: drupal_add_js()/drupal_add_css() should no longer be used

Body: In Drupal 7, drupal_add_js() and drupal_add_css() could be used to add JS and CSS to a page. In Drupal 8, these functions are now private to the internals of the render system and should not be called by modules. Instead, you should use #attached in a render array.

// Code example D7

// Code example D8

---

You can find some examples from the two metas linked in the issue summary.

Proposed Change Notice.

drupal_add_js()/drupal_add_css() should no longer be used

• In Drupal 7, drupal_add_js() and drupal_add_css() could be used to add JS and CSS to a page. In Drupal 8, these functions have been changed to _drupal_add_js() and _drupal_add_css() and are now private to the internals of the render system and should not be called by modules. Instead, you should use #attached in a render array.

Add CSS Code Example D7

drupal_add_css(drupal_get_path('module', 'example') . '/example.css');

Add CSS Code Example D8

$example = array(
  '#attached' => array(		
    'css' => array(drupal_get_path('module', 'example') . '/example.css'),
  ),
);

Add JS Code Example D7

drupal_add_js(drupal_get_path('module', 'example') . '/example.js');

Add JS Code Example D8

$example = array(
  '#attached' => array(		
    'js' => array(drupal_get_path('module', 'example') . '/example.js'),
  ),
);

I added the change notice.

private to the internals of the render system and should not be called by modules

Should this say "must not"? Should and must could be considered technical terms, as they are widely used with RFC 2119 definitions. http://www.ietf.org/rfc/rfc2119.txt

@ianthomas_uk - agreed, made a couple edits to clarify that.

Yay! Now let's get #2171071: Rename drupal_add_library() to _drupal_add_library() and remove its uses in to finish this.