retrieve_widgets

Look for "lost" widgets, this has to run at least on each theme change.

Description

(array|void) retrieve_widgets( (bool) $theme_changed = false ); 

Returns (array|void)

Parameters (1)

0. $theme_changed — Optional. (bool) => false
Whether the theme was changed as a boolean. A value of customize defers updates for the Customizer.

Usage

  1. if ( !function_exists( 'retrieve_widgets' ) ) { 
  2. require_once ABSPATH . WPINC . '/widgets.php'; 
  3.  
  4. // Whether the theme was changed as a boolean. A value 
  5. // of 'customize' defers updates for the Customizer. 
  6. $theme_changed = false; 
  7.  
  8. // NOTICE! Understand what this does before running. 
  9. $result = retrieve_widgets($theme_changed); 
  10.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/widgets.php  
  1. function retrieve_widgets( $theme_changed = false ) { 
  2. global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets; 
  3.  
  4. $registered_sidebar_keys = array_keys( $wp_registered_sidebars ); 
  5. $orphaned = 0; 
  6.  
  7. $old_sidebars_widgets = get_theme_mod( 'sidebars_widgets' ); 
  8. if ( is_array( $old_sidebars_widgets ) ) { 
  9. // time() that sidebars were stored is in $old_sidebars_widgets['time'] 
  10. $_sidebars_widgets = $old_sidebars_widgets['data']; 
  11.  
  12. if ( 'customize' !== $theme_changed ) { 
  13. remove_theme_mod( 'sidebars_widgets' ); 
  14.  
  15. foreach ( $_sidebars_widgets as $sidebar => $widgets ) { 
  16. if ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { 
  17. continue; 
  18.  
  19. if ( !in_array( $sidebar, $registered_sidebar_keys ) ) { 
  20. $_sidebars_widgets['orphaned_widgets_' . ++$orphaned] = $widgets; 
  21. unset( $_sidebars_widgets[$sidebar] ); 
  22. } else { 
  23. if ( empty( $sidebars_widgets ) ) 
  24. return; 
  25.  
  26. unset( $sidebars_widgets['array_version'] ); 
  27.  
  28. $old = array_keys($sidebars_widgets); 
  29. sort($old); 
  30. sort($registered_sidebar_keys); 
  31.  
  32. if ( $old == $registered_sidebar_keys ) 
  33. return; 
  34.  
  35. $_sidebars_widgets = array( 
  36. 'wp_inactive_widgets' => !empty( $sidebars_widgets['wp_inactive_widgets'] ) ? $sidebars_widgets['wp_inactive_widgets'] : array() 
  37. ); 
  38.  
  39. unset( $sidebars_widgets['wp_inactive_widgets'] ); 
  40.  
  41. foreach ( $wp_registered_sidebars as $id => $settings ) { 
  42. if ( $theme_changed ) { 
  43. $_sidebars_widgets[$id] = array_shift( $sidebars_widgets ); 
  44. } else { 
  45. // no theme change, grab only sidebars that are currently registered 
  46. if ( isset( $sidebars_widgets[$id] ) ) { 
  47. $_sidebars_widgets[$id] = $sidebars_widgets[$id]; 
  48. unset( $sidebars_widgets[$id] ); 
  49.  
  50. foreach ( $sidebars_widgets as $val ) { 
  51. if ( is_array($val) && ! empty( $val ) ) 
  52. $_sidebars_widgets['orphaned_widgets_' . ++$orphaned] = $val; 
  53.  
  54. // discard invalid, theme-specific widgets from sidebars 
  55. $shown_widgets = array(); 
  56.  
  57. foreach ( $_sidebars_widgets as $sidebar => $widgets ) { 
  58. if ( !is_array($widgets) ) 
  59. continue; 
  60.  
  61. $_widgets = array(); 
  62. foreach ( $widgets as $widget ) { 
  63. if ( isset($wp_registered_widgets[$widget]) ) 
  64. $_widgets[] = $widget; 
  65.  
  66. $_sidebars_widgets[$sidebar] = $_widgets; 
  67. $shown_widgets = array_merge($shown_widgets, $_widgets); 
  68.  
  69. $sidebars_widgets = $_sidebars_widgets; 
  70. unset($_sidebars_widgets, $_widgets); 
  71.  
  72. // find hidden/lost multi-widget instances 
  73. $lost_widgets = array(); 
  74. foreach ( $wp_registered_widgets as $key => $val ) { 
  75. if ( in_array($key, $shown_widgets, true) ) 
  76. continue; 
  77.  
  78. $number = preg_replace('/.+?-([0-9]+)$/', '$1', $key); 
  79.  
  80. if ( 2 > (int) $number ) 
  81. continue; 
  82.  
  83. $lost_widgets[] = $key; 
  84.  
  85. $sidebars_widgets['wp_inactive_widgets'] = array_merge($lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets']); 
  86. if ( 'customize' !== $theme_changed ) { 
  87. wp_set_sidebars_widgets( $sidebars_widgets ); 
  88.  
  89. return $sidebars_widgets;