Changed behaviour of esc_sql() in WordPress 4.8.3

As part of the WordPress 4.8.3 release, there is a change in `esc_sql()` behaviour that may affect plugin developers who expect `esc_sql()` to return a string that’s usable outside of the context of building a query to send to WPDB.

While we strongly recommend you do not use `esc_sql()` for other purposes, we understand that it can be tricky to rewrite old code rapidly. To return to the old behaviour, you can use the `$wpdb->remove_placeholder_escape()` method, like so:

echo esc_sql( "100%" );
// "100{9fa52f39262a451892931117b9ab11b5a06d3a15faee833cc75edb18b4411d11}"

echo $wpdb->remove_placeholder_escape( esc_sql( "100%" ) );
// "100%"

#4-8, #4-8-3, #dev-notes, #wpdb

Dev Chat Summary: June 7th (4.8 week 6)

This post summarizes the dev chat meeting from June 7th (agendaSlack archive).

4.8 timing recap and Pre-Final Release & Dry Run checklist items

  • Beta 1 went out on Friday, May 12th; Beta 2 went out on Monday, May 22nd
  • RC1 went out on Thursday, May 25th; RC2 went out on Thursday, June 1st
  • 4.8 is scheduled for June 1, 2017 at 9am EDT
  • Events widget looks ready
  • Credits API to be updated by @ocean90 tomorrow morning
  • About page update for responsive, CDN-hosted images coming from @melchoyce
  • Announcement post draft is ready to go; @jorbin & @ocean90 to help provide contributor & language count as input
  • Announcement email being drafted by @matt
  • Codex page to be updated by @jbpaul17
  • Agreed to remove “partial back to IE8” from Browser support page in Design handbook
  • tinymce/plugins/wpembed to be added to $_old_files by @ocean90
  • No new default theme, so $_new_bundled_files is fine
  • Updates to default themes and submission to repo to be done by @davidakennedy, committed by @ocean90
  • Hosts email to be drafted by @jbpaul17, email to be reviewed & sent by @jorbin
  • Systems to be covered by @vnsavage
  • grunt prerelease check for tests & standards to be run by @jorbin

4.8 Bug Scrub

  • Reviewing four tickets in Defects Awaiting Review, reported against trunk section from Report 40
  • #40929: relates to improved translator docs, punting to next minor release (4.8.1)
  • #40932: moved to Future Release
  • #40927: not a regression, moved to Future Release
  • #40906: marked as a dupe of #40685, not a blocker for 4.8

Other News

  • Customize: looking for a new contributor to work on the HTML/Code widget, a good-first-bug, please chat in #core-customize if you’re interested
  • Editor: working to get the plugin in the plugin repo so that more people can review it and provide feedback. Goal is this week.
  • Devchat coordination: will be covered in upcoming devchat

#4-8, #core, #dev-chat, #summary

Dev Chat Agenda for June 7th (4.8 week 6)

This is the agenda for the weekly dev meeting on June 7, 2017 at 20:00 UTC:

  • 4.8 timing
  • 4.8 bug scrub
  • Customize: looking for new contributor to mentor
  • Editor: Gutenberg timing
  • Dev chat coordination
  • General announcements

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-8, #agenda, #core, #dev-chat

Dev Chat Summary: May 31st (4.8 week 5)

This post summarizes the dev chat meeting from May 31st (agendaSlack archive).

4.8 Timing

  • Beta 1 went out on Friday, May 12th; Beta 2 went out on Monday, May 22nd; RC1 went out on Thursday, May 25th
  • RC2 is scheduled for Thursday, June 1st
  • With RC2 we’re aiming for a hard string freeze so that translators can complete all the new strings in 4.8
  • Should things continue to go to plan, 4.8 release would be next Thursday, June 8th

4.8 Bug Scrub

  • Currently at 4 tickets in the milestone, goal is to get to 0 by RC2
  • #39822 has ongoing commits to improve Build/Test Tools in relationship to PHPUnit 6
  • #40893 is a bug that used to be caused by themes, but now there is a notice in the UI about it [Note: since committed and closed]
  • The TinyMCE-extended Text widget provides a suboptimal UX for users who have been accustomed to pasting in 3rd-party JavaScript code (widgets) into the Text widget
    • Relates to #2833
    • Considerations considered include code, documentation, and/or UI updates to improve the UX
    • Suboptimal UX includes three separate but related issues:
      • 1) Extra whitespace from content pasted in
      • 2) HTML being encoded after it is pasted in
      • 3) line breaks in JS causing the JS to break due to new <p>
    • #1 & 2 are likely best solved with documentation and some outreach
    • #3 appears to be the most severe, but also the biggest edge case
    • Proposal:
      • 1) In the very short term, create documentation to help 3rd parties (e.g. MailChimp, Infusionsoft) and utilize people with a wide and respected reach to do some outreach with that documentation
      • 2) For 4.8.0, don’t make any code related changes
      • 3) Continue looking into this and exploring what we could change for 4.8.1
    • Note the TinyMCE Text Widget post has been amended to note the need to remove extraneous line breaks, especially when pasting in script snippets
    • If you’re able to help with documentation or outreach on this, please call out in #core.
  • #40865 has patch, needs review for commit in 4.8/punt to 4.8.1
  • #40721 committing final strings tonight, only hours remain for feedback

4.8 Dev Notes / Field Guide

  • Many thanks to all writing, reviewing, and otherwise contributing to getting all the dev notes published recently!
  • Also 🙌 to @pbiron & @desrosj for their help getting the field guide published alongside RC1

Other News

#4-8, #dev-chat, #summary

Dev Chat Agenda for May 31st (4.8 week 5)

This is the agenda for the weekly dev meeting on May 31, 2017 at 20:00 UTC:

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-8, #agenda, #core, #dev-chat

WordPress 4.8 Field Guide

WordPress 4.8 is officially the best WordPress 2017 has seen!  Users will receive new and refined features focused on Editing and Customizing their sites while developers will be able to take advantage of 109 enhancements and features added.  Let’s look at the many improvements coming in 4.8…


Media Widgets

Not one, not two, but three new media widgets make their way into core. It’s like the AV crew just showed up and now the party can really begin. You get an audio widget. You get an image widget. You get a video widget. Check under your seat, media widgets for everyone!

Media Widgets for Images, Video, and Audio


Fabulously Rich Text Widget

Robin Hood has come to town and is handing out rich text editing to all the text widgets. No more having to manually type out your HTML in text widgets like it’s 2016.

Addition of TinyMCE to the Text Widget


Simpler Link Editing, Streamlined Browser Support, and Editor Instantiation via JS

Editing just got a lot easier, you can thank us later. But trust us that adding and managing links within the editor is now easier than ever. If you don’t trust us, then just try navigating in and out of links with your arrow keys. Pretty cool, huh? That’s the new TinyMCE inline element / link boundaries. As for the reduced browser support, let’s just say IE 8, 9, and 10 have been thanked for their service but can feel free to enjoy their retirement. Also, if bootstrapping the TinyMCE content editor dynamically via JS is your thing, then boy are you going to be excited!

Editor changes in 4.8

Editor API changes in 4.8


WMV and WMA get retirement packages

Remember Silverlight? Many browsers these days don’t. So the file formats which require the presence of the Silverlight plugin are being removed from core support. Files will still display as a download link, but will no longer be embedded automatically.

Removal of core embedding support for WMV and WMA file formats


Resizing the Customizer sidebar

If you have used the Customizer on a high-resolution screen, then you may have noticed that the Customizer sidebar is… suboptimally narrow. The sidebar is now variable width based on screen size to help you receive the best editing experience possible.

Customizer sidebar width is now variable


WordCamps and meetups all up in your admin dashboard

One of the best things about WordPress is its community. You can now read about WordCamps and meetups in your area right within your dashboard. No more excuses for missing the speaker or volunteer deadlines now!

Nearby WordPress Events

Showing upcoming local events in wp-admin


Mu will really love these multisite changes

We know you love superheroes but is_super_admin() needs to go. So while we’re replacing that with appropriate capabilities, we’re also treating you to some new hooks and a new $network_id parameter that gets wide usage across several functions.

Multisite Focused Changes in 4.8


Accessibility: saving the best for last

As a part of ongoing efforts to improve accessibility in WordPress, 4.8 includes some changes to headings within admin screens. This is a continuation of the work started in 4.3 on restoring the H1 (heading level 1) to the admin screens and continued in 4.4 with the introduction of a better headings hierarchy. Also improved is the Tag Cloud widget, now swapping out the title attributes in favor of aria-label attributes.

Cleaner headings in the admin screens

Tag Cloud widget changes in 4.8


But Wait, There is More!

Roughly 217 bugs, 108 enhancements, 1 feature request, and 16 blessed tasks have been marked as closed in WordPress 4.8. Some additional ones to highlight include:

  • REST API: orderby normalization (#38693)
  • REST API: Add supports object to /types response (#39033)
  • New filter to disable auto-focus on the login screen (#40301)
  • was added as an oEmbed provider (#38367)
  • HHVM removed from the test matrix on Travis (#40548)
  • Bundled Themes now support the new media and updated text widgets (#40745)
  • Popular plugins feed has been removed from the dashboard (#40702)
  • Support added for Bosnian locale (bs_BA) in remove_accents() (#39658)
  • Easily enqueue WP_Editor JavaScript files using the new wp_enqueue_editor() (#35760)

New Action Hooks

  • deleted_blog (#25584)
  • print_default_editor_scripts (#35760)

New Filter Hooks

  • file_mod_allowed replaces disallow_file_mods (#38673)
  • minimum_site_name_length (#39676)
  • nav_menu_submenu_css_class (#36163)
  • page_menu_link_attributes (#40359)
  • post_date_column_status (#39545)
  • signup_site_meta (#39223)
  • signup_user_meta (#39223)
  • wp_doing_cron (#39591)
  • widget_text_content (#40772)
  • rest_oembed_ttl (#40450)
  • widget_{$this->id_base}_instance (#32417)

Modified Filter Hooks

  • widget_text_content (#40772)
  • {$type}_template (#39525)
  • display_media_states (#39628)
  • media_library_show_audio_playlist (#31071)
  • media_library_show_video_playlist (#31071)
  • rest_pre_insert_comment (#39578)
  • wp_is_large_network (#40489)

External Library Updates

  • TinyMCE was updated from version 4.5.6 to version 4.6.2 (see: #40859).
  • Twemoji was updated from version 2.2.2 to version 2.3.0 (see: #40858).
  • zxcvbn was updated from version 1.0 to version 4.4.1 (see: #31647).

Please, test your code. That bears repeating: Please, test your code. Fixing issues now, before 4.8 is released, helps you and helps millions of WordPress sites. Please. Test. Your. Code.

#4-8, #field-guide

Media Widgets for Images, Video, and Audio

As first introduced in the Image Widget Merge Proposal, WordPress 4.8 includes media widgets (#32417) for not only images (#39993) but also video (#39994) and audio (#39995), on top of an extensible base for introducing additional media widgets in the future, such as for galleries and playlists. To quote [40640]:

The last time a new widget was introduced, Vuvuzelas were a thing, Angry Birds started taking over phones, and WordPress stopped shipping with Kubrick. Seven years and 17 releases without new widgets have been enough, time to spice up your sidebar!

Since widgets are a very old part of WordPress (since 2.2), widgets in core have been very much entirely built using PHP with some Ajax sprinkled on top. In the time since WP_Widget was introduced in 2.8, WordPress has made dramatic shifts toward developing interfaces in JavaScript, including with the Customizer in 3.4 and the Media Library in 3.5, and more recently with the focus on the REST API and the editor (Gutenberg).

Given that the media widgets are naturally interfacing with the media library JS, it is necessary that the media widgets make use of JavaScript to construct their UI instead of relying on PHP. The media widgets fully reuse the existing media modal frames for not only selecting the media to display but also to edit all of its properties: attachments can be selected from the media library, while external media can be inserted by URL.

Initial groundwork for shimming JavaScript into widgets was added in 3.9 via the widget-added and widget-updated events, which are also being utilized in 4.8 with the Addition of TinyMCE to the Text Widget. A more recent proposal for making JavaScript more of a first class citizen can be found in #33507 and the media widgets incorporate some of its patterns that were also prototyped in the JS Widgets plugin. The media widgets make use of a Backbone View to manage the widget control’s UI and a Backbone Model for reading and manipulating the widget instance data.

Base Media Widget

PHP: wp-includes/widgets/class-wp-widget-media.php
JS: wp-admin/js/widgets/media-widgets.js

The three widgets all extend a WP_Widget_Media PHP abstract class; in JS the Backbone view wp.mediaWidgets.MediaWidgetControl and wp.mediaWidgets.MediaWidgetModel are extended. A unique aspect of how the media widgets work is how instance data is validated and sanitized. Normally widgets utilize procedural code to sanitize instances via a subclassed WP_Widget::update() method. The media widgets, however, make use of a REST API schema returned from WP_Widget_Media::get_instance_schema() to sanitize instances declaratively. The WP_Widget_Media::update() method iterates over the schema and uses it to sanitize and validate the instance properties. (Adding schemas to the base WP_Widget class is also proposed in #35574.) The JSON schema is extended to include a couple custom properties: media_prop provides the media JS property name that the widget instance maps, and the should_preview_update flag indicates whether a change to that prop should cause the control preview to re-render (this would be retired with a React rewrite and/or leveraging of corresponding blocks in Gutenberg).

The WP_Widget_Media abstract class has one abstract method which subclasses must implement: WP_Widget_Media::render_media(). This is the method that WP_Widget_Media::widget() calls with the $instance props to render the media for a given widget media type. Before the props are passed to the method, the $instance is applied through  widget_{$id_base}_instance filters.

A media widget subclass should output additional JS templates as the control needs by extending WP_Widget_Media::render_control_template_scripts(). Scripts that the widget control requires can be enqueued by extending WP_Widget_Media::enqueue_admin_scripts(); this is also where the PHP exports can be done with calls to wp_add_inline_script().

The REST API schema is exported from PHP to JS on the subclassed MediaWidgetModel prototypes. Other properties on the prototypes which should be extended include l10n and mime_type. The model subclasses are registered by assigning them to the wp.mediaWidgets.modelConstructors object, keyed by the widget ID base (e.g. media_image, media_video, etc). In the same way, the Backbone View wp.mediaWidgets.MediaWidgetControl is subclassed and registered by adding to the wp.mediaWidgets.controlConstructors object, also keyed by widget ID base. This is similar to how control types are registered in the Customizer.

The MediaWidgetControl and MediaWidgetModel will be instantiated once a widget control is expanded. Their instances will be then added to the wp.mediaWidgets.widgetControls object and wp.mediaWidgets.modelCollection respectively.

There is a subclass of a media controller and a couple media views in the wp.mediaWidgets namespace. These extensions to media classes are needed due to current limitations in media extensibility. They may be removed/reduced with improvements in #40427.

As with the incorporation of TinyMCE into the Text widget, the incorporation of the media library into the media widget has necessitated constructing the widget’s form fields differently than how they are normally done. Widgets in core have historically utilized static HTML for their control form fields. Every time a user hits “Save” the form fields get sent in an Ajax request which passes them to the WP_Widget::update() method and then the Ajax response sends back the output of WP_Widget::form() which then replaces the entire form. (Note widgets in the Customizer behave differently since there is no Save button in the widget, as updates are synced and previewed as changes are made; read more about Live Widget Previews.) This worked for static HTML forms in the past, but in the case of the media widgets the UI built with JavaScript instead of server-side PHP.

To avoid having to rebuild the media preview every time the user hits Save on the admin screen, the media widget puts its UI elements outside of the container that is “managed” by the server which gets replaced with each save. (A similar approach has also been employed by the new TinyMCE-extended Text widget in 4.8.) Since core does not yet represent a widget’s state in a JavaScript model (again see #33507), the media widget syncs its MediaWidgetModel props with hidden inputs that get rendered by WP_Media_Widget::form() in order to be sent to the server for preview and saving. The container for the media widget’s fields is .media-widget-control and the traditional container for a widget’s input fields as rendered by WP_Widget::form() is .widget-content:

For examples of how to implement media widgets, see the three implementations included in 4.8 as follows.

Image Widget

PHP: wp-includes/widgets/class-wp-widget-media-image.php
JS: wp-admin/js/widgets/media-image-widget.js

Field Type Default Description
attachment_id integer 0 Attachment post ID
url string "" URL to the media file
title string "" Title for the widget
size string "medium" Size
width integer 0 Width
height integer 0 Height
caption string "" Caption
alt string "" Alternative Text
link_type string "none" Link To
link_url string "" URL
image_classes string "" Image CSS Class
link_classes string "" Link CSS Class
link_rel string "" Link Rel
link_target_blank boolean false Open link in a new tab
image_title string "" Image Title Attribute

Video Widget

PHP: wp-includes/widgets/class-wp-widget-media-video.php
JS: wp-admin/js/widgets/media-video-widget.js

The video widget allows for embeddable video formats to be selected from the media library or linked to externally by URL. In addition, URLs to YouTube or Vimeo may also be provided since the video shortcode logic supports rendering them via MediaElement.js. It is possible for plugins to add support for additional oEmbed providers via extending the video widget control’s isHostedVideo method; for more, see the Jetpack PR for adding VideoPress support.

Field Type Default Description
attachment_id integer 0 Attachment post ID
url string "" URL to the media file
title string "" Title for the widget
preload string "metadata" Preload
loop boolean false Loop
content string "" Tracks (subtitles, captions, descriptions, chapters, or metadata)
mp4 string "" URL to the mp4 video source file
m4v string "" URL to the m4v video source file
webm string "" URL to the webm video source file
ogv string "" URL to the ogv video source file
flv string "" URL to the flv video source file

Note that the presence of format-specific fields is dependent on what is returned by wp_get_video_extensions().

Audio Widget

PHP: wp-includes/widgets/class-wp-widget-media-audio.php
JS: wp-admin/js/widgets/media-audio-widget.js

The audio widget allows for embeddable audio formats to be selected from the media library or linked to externally by URL. Note that there are no oEmbed audio formats supported since the audio shortcode logic only supports rendering players for actual audio files.

Field Type Default Description
attachment_id integer 0 Attachment post ID
url string "" URL to the media file
title string "" Title for the widget
preload string "none" Preload
loop boolean false Loop
mp3 string "" URL to the mp3 audio source file
ogg string "" URL to the ogg audio source file
m4a string "" URL to the m4a audio source file
wav string "" URL to the wav audio source file

Note that the presence of format-specific fields is dependent on what is returned by wp_get_audio_extensions().

Default Themes Updates

Themes that add custom styles to the MediaElement.js player (namely Twenty Thirteen and Twenty Fourteen) were updated from just styling it within syndicated content, to also include instances within widgets. Most themes don’t restrict styles for captioned images or media players to just post content, that is, limit CSS selectors to classes output by post_class(). If your theme does, make sure to either remove that constraint or include a .widget selector.


The work on the new media widgets in core was conducted in the Core Media Widgets plugin and on its corresponding wp-core-media-widgets GitHub repo. Many of the decisions that were made in the architecture of the feature can be found there in the GitHub issues and pull requests.

Keep in mind that the media widgets will likely undergo many more changes with the incorporation of the Gutenberg editor, and that widgets themselves will likely see many changes to align with Gutenberg’s editor blocks which are now being prototyped. Essentially if you can insert a given type of block into the editor, there should also be a widget available for representing the same content.

#4-8, #dev-notes, #media-widgets

Tag Cloud widget changes in 4.8

The Tag Cloud widget is still pretty popular and for a number of years, it has used title attributes to visually display the number of posts using a specific tag.

tag cloud in WordPress 4.7

Example of a title attribute displaying the number of items for a specific tag in WordPress 4.7

WordPress 4.8 removes these title attributes and replaces them with aria-label attributes with optional counts displayed in plain text.

Why it matters

Title attributes aren’t very accessible. Depending on the specific assistive technology and on user settings, they might be completely ignored. On touch devices, title attributes are a bit pointless.

The best option is not to rely on title attributes to convey important information to users. Information that is important enough should be available to all users.

In the last few releases, WordPress has been progressively removing many title attributes used in the admin screens (see: #24766). The same principle applies to the front end. The Tag Cloud widget is another step towards the progressive removal of title attributes in the front end where they’re used inappropriately.

What plugin or theme authors should know

There are no visual changes by default, other than the removal of the title attributes. There is a new option for developers though: tag counts can be displayed in plain text within the list of tags. Users will now find a checkbox in the widget interface, consistent with what other widgets already do (e.g., Archives and Categories widgets).

the tag cloud widget admin interface

The new option “Show tag counts” in the widget admin interface

Checking the “Show tag counts” option in the admin will make the Tag Cloud show the counts alongside each tag. The screenshot below compares the Tag Cloud with and without the counts displayed:
the Tag Cloud with and without tag counts

Themes can style the tag counts targeting the new CSS class tag-link-count. Also, note that wp_generate_tag_cloud() has a new show_count argument. Themes and plugins that filter the Tag Cloud arguments can use this new argument to force the tag counts to be displayed.

Theme authors are recommended to check how the tag counts look like in their themes and make small CSS adjustments if needed. And remember, the tag counts are not displayed by default! Users can enable and also disable them at any time.

Some technical details

The relevant changeset is [40816] and the related ticket is #35566. Behind the scenes, the tag cloud now attempts to determine whether to output the aria-label attribute, trying to respect the theme author’s intent.

By default, the Tag Cloud displays tags in different font sizes to visually represent how many times they’re used. When tags have a different font size, they visually convey important information that should also be available to assistive technologies.

Sometimes instead, theme authors set up the Tag Cloud to display all tags with the same font size. Twenty Sixteen, for example, displays all the tags with a “flat” styling. It does that by filtering the arguments passed to wp_generate_tag_cloud() and setting the smallest and largest arguments to the same value (note: this is the recommended way to output “flat” tags).

In order to always serve the same information to all users and try to respect the theme author’s intent, the aria-label that conveys the count information to assistive technologies gets printed out:

  • when tags have a different size
  • when the tag count is displayed in plain text (for example when users check the checkbox in the Tag Cloud widget), regardless of the tags font size

A quick update about title attributes

To give an idea of the progress done so far, here’s data from the WordPress codebase from version 4.0 to 4.7. Searching for occurrences of  title= (space-title-equal) only within .php files and only in the wp-admin directory:

WordPress 4.0: 157 results found in 37 files
WordPress 4.1: 156 results found in 37 files
WordPress 4.2: 146 results found in 35 files
WordPress 4.3: 101 results found in 30 files
WordPress 4.4: 97 results found in 32 files
WordPress 4.5: 21 results found in 12 files
WordPress 4.6: 19 results found in 11 files
WordPress 4.7: 17 results found in 9 files

Of the 17 title attributes in WordPress 4.7, four of them are legitimate because they’re used on <iframe> elements and most of the other ones are in files no longer used by core. Many of these occurrences were within loops so the number of title attributes actually output was higher, yet going from 157 down to a very few is wonderful progress.

As always, any comments and contribution to improving accessibility are welcome!

#4-8, #accessibility, #dev-notes

Dev Chat Summary: May 24th (4.8 week 4)

This post summarizes the dev chat meeting from May 24th (agendaSlack archive).

4.8 Timing

  • Beta 1 went out on Friday, May 12th; Beta 2 went out on Monday, May 22nd
  • RC1 is scheduled for Thursday, May 25th
  • With RC1 we’re aiming for a soft string freeze so that translators can work through all the new strings in 4.8
  • Should things continue to go to plan, RC2 would be next Thursday, June 1st

4.8 Bug Scrubs

4.8 Dev Notes / Field Guide

  • Goal is to have Dev Notes all done ASAP so we can assemble the Field Guide by RC1
  • Remaining Dev Notes to get published:
  • Listing of all tickets tagged with needs-dev-note

About Page

  • #40721: dev help needed writing copy for the Under the Hood section, please ping @melchoyce if you can help

#4-8, #core, #dev-chat, #summary

Editor changes in 4.8

There are couple of noteworthy changes to the editor in WordPress 4.8.

A much better experience when trying to place the cursor around links. Try inserting a link, then move the cursor with the left and right arrow keys. You can clearly see when it is inside the link element and when it is before or after it.

Following the earlier announcement, support for Internet Explorer 8, 9, and 10 has been removed from the editor.

As always there have been a lot of improvements and bug fixes, upstream in TinyMCE, and in core.

#4-8, #editor