WordPress.org
Get WordPress

Make WordPress Core

Changeset 20586


Ignore:
Timestamp:
04/25/2012 04:37:49 PM (14 years ago)
Author:
nacin
Message:

Documentation and visibility cleanups in WP_Theme.

  • Declare __toString() as public.
  • Use parent() and error() internally, rather than the properties.
  • Add and correct inline documentation throughout.
  • Attempt to clarify that display() is superior to get().

see #20546, see #20103.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/class-wp-theme.php

    r20481 r20586  
    291291     * @return string Theme name, ready for display (translated)
    292292     */
    293     function __toString() {
     293    public function __toString() {
    294294        return (string) $this->display('Name');
    295295    }
    … …  
    318318                return $this->get('Version');
    319319            case 'parent_theme' :
    320                 return $this->parent ? $this->parent->get('Name') : '';
     320                return $this->parent() ? $this->parent()->get('Name') : '';
    321321            case 'template_dir' :
    322322                return $this->get_template_directory();
    … …  
    370370
    371371    /**
    372      * Method to implement ArrayAccess for keys formerly returned by get_themes()
     372     * Method to implement ArrayAccess for keys formerly returned by get_themes().
     373     *
     374     * Author, Author Name, Author URI, and Description did not previously return
     375     * translated data. We are doing so now as it is safe to do. However, as
     376     * Name and Title could have been used as the key for get_themes(), both remain
     377     * untranslated for back compatibility. This means that ['Name'] is not ideal,
     378     * and care should be taken to use $theme->display('Name') to get a properly
     379     * translated header.
    373380     */
    374381    public function offsetGet( $offset ) {
    375382        switch ( $offset ) {
    376383            case 'Name' :
    377             case 'Version' :
    378             case 'Status' :
    379                 return $this->get( $offset );
    380384            case 'Title' :
     385                // See note above about using translated data. get() is not ideal.
     386                // It is only for backwards compatibility. Use display().
    381387                return $this->get('Name');
    382             // Author, Author Name, Author URI, and Description did not
    383             // previously return translated data. We are doing so now.
    384             // Title and Name could have been used as the key for get_themes(),
    385             // so both to remain untranslated for back compatibility.
    386388            case 'Author' :
    387389                return $this->display( 'Author');
    … …  
    392394            case 'Description' :
    393395                return $this->display( 'Description');
     396            case 'Version' :
     397            case 'Status' :
     398                return $this->get( $offset );
    394399            case 'Template' :
    395400                return $this->get_template();
    … …  
    419424                return $this->get_theme_root_uri();
    420425            case 'Parent Theme' :
    421                 return $this->parent ? $this->parent->get('Name') : '';
     426                return $this->parent() ? $this->parent()->get('Name') : '';
    422427            default :
    423428                return null;
    … …  
    441446     *
    442447     * A theme with errors exists. A theme with the error of 'theme_not_found',
    443      * meaning that the theme directory was not found, does not exist.
     448     * meaning that the theme's directory was not found, does not exist.
    444449     *
    445450     * @since 3.4.0
    … …  
    449454     */
    450455    public function exists() {
    451         return ! ( is_wp_error( $this->errors ) && in_array( 'theme_not_found', $this->errors->get_error_codes() ) );
     456        return ! ( $this->errors() && in_array( 'theme_not_found', $this->errors()->get_error_codes() ) );
    452457    }
    453458
    … …  
    510515
    511516    /**
    512      * Gets a theme header.
    513      *
    514      * The header is sanitized.
    515      *
    516      * @access public
    517      * @since 3.4.0
    518      *
    519      * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status.
     517     * Get a raw, unformatted theme header.
     518     *
     519     * The header is sanitized, but is not translated, and is not marked up for display.
     520     * To get a theme header for display, use the display() method.
     521     *
     522     * Use the get_template() method, not the 'Template' header, for finding the template.
     523     * The 'Template' header is only good for what was written in the style.css, while
     524     * get_template() takes into account where WordPress actually located the theme and
     525     * whether it is actually valid.
     526     *
     527     * @access public
     528     * @since 3.4.0
     529     *
     530     * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
    520531     * @return string String on success, false on failure.
    521532     */
    … …  
    546557
    547558    /**
    548      * Gets a theme header ready for display (marked up, translated).
    549      *
    550      * @access public
    551      * @since 3.4.0
    552      *
    553      * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status.
     559     * Gets a theme header, formatted and translated for display.
     560     *
     561     * @access public
     562     * @since 3.4.0
     563     *
     564     * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
    554565     * @param bool $markup Optional. Whether to mark up the header. Defaults to true.
    555566     * @param bool $translate Optional. Whether to translate the header. Defaults to true.
    … …  
    574585     * Sanitize a theme header.
    575586     *
    576      * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status.
     587     * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
    577588     * @param string $value Value to sanitize.
    578589     */
    … …  
    626637     * @since 3.4.0
    627638     *
    628      * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status.
     639     * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
    629640     * @param string $value Value to mark up.
    630641     * @param string $translate Whether the header has been translated.
    … …  
    673684     * @since 3.4.0
    674685     *
    675      * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status.
     686     * @param string $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
    676687     * @param string $value Value to translate.
    677688     * @return string Translated value.
    … …  
    764775     */
    765776    public function get_stylesheet_directory() {
    766         if ( $this->errors && in_array( 'theme_root_missing', $this->errors->get_error_codes() ) )
     777        if ( $this->errors() && in_array( 'theme_root_missing', $this->errors()->get_error_codes() ) )
    767778            return '';
    768779
    … …  
    782793     */
    783794    public function get_template_directory() {
    784         if ( $this->parent )
    785             $theme_root = $this->parent->theme_root;
     795        if ( $this->parent() )
     796            $theme_root = $this->parent()->theme_root;
    786797        else
    787798            $theme_root = $this->theme_root;
    … …  
    817828     */
    818829    public function get_template_directory_uri() {
    819         if ( $this->parent )
    820             $theme_root_uri = $this->parent->get_theme_root_uri();
     830        if ( $this->parent() )
     831            $theme_root_uri = $this->parent()->get_theme_root_uri();
    821832        else
    822833            $theme_root_uri = $this->get_theme_root_uri();
    … …  
    865876     *
    866877     * Screenshots for a theme must be in the stylesheet directory. (In the case of a child
    867      * theme, a parent theme's screenshots are inherited.)
     878     * theme, a parent theme's screenshots are not inherited.)
    868879     *
    869880     * @since 3.4.0
    … …  
    10311042     *
    10321043     * @param string $path Absolute path to search.
    1033      * @param array|string $extensions Array of extensions to find, or string of a single extension
     1044     * @param mixed  Array of extensions to find, string of a single extension, or null for all extensions.
    10341045     * @param int $depth How deep to search for files. Optional, defaults to a flat scan (0 depth). -1 depth is infinite.
    10351046     * @param string $relative_path The basename of the absolute path. Used to control the returned path
Note: See TracChangeset for help on using the changeset viewer.