[wp-trac] [WordPress Trac] #20546: WP_Theme cleanups: get_files, scandir, is_child_theme, multiple screenshot support

[WordPress Trac]

#20546: WP_Theme cleanups: get_files, scandir, is_child_theme, multiple screenshot
support
--------------------------+-----------------
 Reporter:  nacin         |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  3.4
Component:  Themes        |    Version:
 Severity:  normal        |   Keywords:
--------------------------+-----------------
 After looking closely at the WP_Theme API in the weeks that have followed
 #20103, implementing it in a few areas, and seeing how it settled, I have
 a few final changes to make to the public API.

 == Remove the is_child_theme() method ==

 is_child_theme() simply checks if template !== stylesheet. However, it is
 possible for it to be a child theme under this definition, but to not have
 a valid parent. This means code like this: `if ( $theme->is_child_theme()
 ) echo $theme->parent()->display('Name');` can potentially fatal error. I
 made this mistake at least once, which doesn't bode well for others.

 Thus, we can eliminate is_child_theme() as a direct counterpart to the
 global function. That is fine, as you still have $this->parent() to check,
 a method that came later in my development and definitely makes more
 sense. Otherwise you have two very, very similar methods, and mixing them
 up can cause fatal errors in edge cases. Yuck.

 == Remove multiple screenshot support ==

 api.wordpress.org and WP_Theme are both ready for multiple screenshots,
 but they aren't displayed anywhere in the UI. We should remove
 get_screenshots() and get_screenshot_count() until or if we decide to
 implement them in the UI.

 == Generalize the get_files method ==

 get_files() was originally designed to cache and return a theme's CSS and
 PHP files. This gets complicated quickly due to child/parent and depth
 differences. get_themes() looked one directory deep for PHP files in the
 parent theme, top-level only for CSS and PHP files in a child theme, and
 avoided looking for CSS files in the parent theme all together. This is
 pretty inconsistent, something I tried to standardize, especially given
 our needs with page templates (we want all PHP files from a consistent
 depth in both themes) and the theme editor (we no longer show inherited
 files from a parent theme).

 get_files() also has an odd return value, in that it can return an array
 of 'css' and 'php' keys, with an array of matching files as the values. I
 wrote this when I hadn't yet ported things over to the theme editor. It
 seems unnecessary. Likewise, caching here seems unnecessary, and makes
 things inflexible. Right now, a plugin would need to implement their own
 method to scan a theme for, say, .png or .js files, and that's lame.

 So. get_files() can become a public function with the following
 definition:

 {{{
 get_files( $type = null, $depth = 0, $search_parent = false )
 }}}

 By default, return all files, flat search, of that theme only (don't
 include the parent).

 Core would use it like so:

 {{{
 // Theme editor:
 $theme->get_files( 'php', 1 );
 $theme->get_files( 'css' );
 // back compat for 'Template Files' and 'Stylesheet Files'
 get_files( 'php', 1, true );
 get_files( 'css' );
 // getting page templates (avoids parent files, we get those separately,
 so they can both be cached)
 $this->get_files( 'php', 1 );
 }}}

 The $search_parent arg is purely for plugins to use.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/20546>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software