WordPress.org
Get WordPress

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

User:Chrisbliss18/wp cache add

This article is a ROUGH DRAFT. The author is still working on this document, so please do not edit this without the author's permission. The content within this article may not yet be verified or valid. This information is subject to change.

Description

bool wp_cache_add ( int|string $key, mixed $data [, string $flag [, int $expire ]] )

This function is part of the WP Cache system. Its function is to add data to the cache, if the cache key doesn't already exist.

For examples of how to use this function, see the Examples section below.

Parameters

This function uses PHP function style parameters.

key
The cache ID to use for retrieval later. This is a required parameter.
data
The data to add to the cache store. This is a required parameter.
flag
The group to add the cache to. Default value is an empty string.

It should be noted that the default value for this parameter in both WP_Object_Cache::add() and WP_Object_Cache::set() is default rather than an empty string. This editor does not know if this difference was an oversight or intentional.
expire
When the cache data should expire. Default value is 0.

Tracing this variable through the resulting call to WP_Object_Cache::set(), it can be seen that this parameter is not used. This may just be a placeholder for future functionality.

Return Values

The function returns true on success and false if the cache ID and group already exists.

Errors/Exceptions

Placeholder section that would be used with functions that return WP Error objects.

ChangeLog

Version Description
2.5 $data filtering is removed.
2.1.1 $data is filtered through first serialize() and then unserialize().
2.0.0 Added to WordPress core.

Examples

There are many examples throughout WordPress' core that use this function. Below are a couple of code selections.

Retrieving All Category IDs

The Function Reference/Category API shows a very good example of using wp_cache_add() in combination with wp_cache_get() to ensure that the expensive queries and data processing to gather all the category IDs only occur once.

Note: The following code was taken from wp-includes/category.php version 2.7. 

<code style="color: #000000"><span style="color: #0000BB"><?php
</span><span style="color: #007700">function </span><span style="color: #0000BB">get_all_category_ids</span><span style="color: #007700">() {
    if ( ! </span><span style="color: #0000BB">$cat_ids </span><span style="color: #007700">= </span><span style="color: #0000BB">wp_cache_get</span><span style="color: #007700">( </span><span style="color: #DD0000">'all_category_ids'</span><span style="color: #007700">, </span><span style="color: #DD0000">'category' </span><span style="color: #007700">) ) {
    </span><span style="color: #0000BB">$cat_ids </span><span style="color: #007700">= </span><span style="color: #0000BB">get_terms</span><span style="color: #007700">( </span><span style="color: #DD0000">'category'</span><span style="color: #007700">, </span><span style="color: #DD0000">'fields=ids&get=all' </span><span style="color: #007700">);
        </span><span style="color: #0000BB">wp_cache_add</span><span style="color: #007700">( </span><span style="color: #DD0000">'all_category_ids'</span><span style="color: #007700">, </span><span style="color: #0000BB">$cat_ids</span><span style="color: #007700">, </span><span style="color: #DD0000">'category' </span><span style="color: #007700">);
    }
    
    return </span><span style="color: #0000BB">$cat_ids</span><span style="color: #007700">;
}
</span><span style="color: #0000BB">?></span></code>

Display Recent Entries Widget

The code that displays the Recent Entries widget provides a good example of how much code can be skipped by using caching.

Note: The following code was taken from wp-includes/widgets.php version 2.7. 

<code style="color: #000000"><span style="color: #0000BB"><?php
</span><span style="color: #007700">function </span><span style="color: #0000BB">wp_widget_recent_entries</span><span style="color: #007700">(</span><span style="color: #0000BB">$args</span><span style="color: #007700">) {
    if ( </span><span style="color: #DD0000">'%BEG_OF_TITLE%' </span><span style="color: #007700">!= </span><span style="color: #0000BB">$args</span><span style="color: #007700">[</span><span style="color: #DD0000">'before_title'</span><span style="color: #007700">] ) {
        if ( </span><span style="color: #0000BB">$output </span><span style="color: #007700">= </span><span style="color: #0000BB">wp_cache_get</span><span style="color: #007700">(</span><span style="color: #DD0000">'widget_recent_entries'</span><span style="color: #007700">, </span><span style="color: #DD0000">'widget'</span><span style="color: #007700">) )
            return print(</span><span style="color: #0000BB">$output</span><span style="color: #007700">);
        </span><span style="color: #0000BB">ob_start</span><span style="color: #007700">();
    }

    </span><span style="color: #0000BB">extract</span><span style="color: #007700">(</span><span style="color: #0000BB">$args</span><span style="color: #007700">);
    </span><span style="color: #0000BB">$options </span><span style="color: #007700">= </span><span style="color: #0000BB">get_option</span><span style="color: #007700">(</span><span style="color: #DD0000">'widget_recent_entries'</span><span style="color: #007700">);
    </span><span style="color: #0000BB">$title </span><span style="color: #007700">= empty(</span><span style="color: #0000BB">$options</span><span style="color: #007700">[</span><span style="color: #DD0000">'title'</span><span style="color: #007700">]) ? </span><span style="color: #0000BB">__</span><span style="color: #007700">(</span><span style="color: #DD0000">'Recent Posts'</span><span style="color: #007700">) : 
        </span><span style="color: #0000BB">apply_filters</span><span style="color: #007700">(</span><span style="color: #DD0000">'widget_title'</span><span style="color: #007700">, </span><span style="color: #0000BB">$options</span><span style="color: #007700">[</span><span style="color: #DD0000">'title'</span><span style="color: #007700">]);
    if ( !</span><span style="color: #0000BB">$number </span><span style="color: #007700">= (int) </span><span style="color: #0000BB">$options</span><span style="color: #007700">[</span><span style="color: #DD0000">'number'</span><span style="color: #007700">] )
        </span><span style="color: #0000BB">$number </span><span style="color: #007700">= </span><span style="color: #0000BB">10</span><span style="color: #007700">;
    else if ( </span><span style="color: #0000BB">$number </span><span style="color: #007700">< </span><span style="color: #0000BB">1 </span><span style="color: #007700">)
        </span><span style="color: #0000BB">$number </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;
    else if ( </span><span style="color: #0000BB">$number </span><span style="color: #007700">> </span><span style="color: #0000BB">15 </span><span style="color: #007700">)
        </span><span style="color: #0000BB">$number </span><span style="color: #007700">= </span><span style="color: #0000BB">15</span><span style="color: #007700">;

    </span><span style="color: #0000BB">$r </span><span style="color: #007700">= new </span><span style="color: #0000BB">WP_Query</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'showposts' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$number</span><span style="color: #007700">, </span><span style="color: #DD0000">'what_to_show' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'posts'</span><span style="color: #007700">,
        </span><span style="color: #DD0000">'nopaging' </span><span style="color: #007700">=> </span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #DD0000">'post_status' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'publish'</span><span style="color: #007700">, </span><span style="color: #DD0000">'caller_get_posts' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));
    if (</span><span style="color: #0000BB">$r</span><span style="color: #007700">-></span><span style="color: #0000BB">have_posts</span><span style="color: #007700">()) :
</span><span style="color: #0000BB">?>
</span>        <span style="color: #0000BB"><?php </span><span style="color: #007700">echo </span><span style="color: #0000BB">$before_widget</span><span style="color: #007700">; </span><span style="color: #0000BB">?>
</span>            <span style="color: #0000BB"><?php </span><span style="color: #007700">if ( !empty( </span><span style="color: #0000BB">$title </span><span style="color: #007700">) ) { echo </span><span style="color: #0000BB">$before_title </span><span style="color: #007700">. </span><span style="color: #0000BB">$title </span><span style="color: #007700">. </span><span style="color: #0000BB">$after_title</span><span style="color: #007700">; } </span><span style="color: #0000BB">?>
</span>            <ul>
            <span style="color: #0000BB"><?php  </span><span style="color: #007700">while (</span><span style="color: #0000BB">$r</span><span style="color: #007700">-></span><span style="color: #0000BB">have_posts</span><span style="color: #007700">()) : </span><span style="color: #0000BB">$r</span><span style="color: #007700">-></span><span style="color: #0000BB">the_post</span><span style="color: #007700">(); </span><span style="color: #0000BB">?>
</span>            <li><a href="<span style="color: #0000BB"><?php the_permalink</span><span style="color: #007700">() </span><span style="color: #0000BB">?></span>">
                <span style="color: #0000BB"><?php </span><span style="color: #007700">if ( </span><span style="color: #0000BB">get_the_title</span><span style="color: #007700">() ) </span><span style="color: #0000BB">the_title</span><span style="color: #007700">(); else </span><span style="color: #0000BB">the_ID</span><span style="color: #007700">(); </span><span style="color: #0000BB">?>
</span>            </a></li>
            <span style="color: #0000BB"><?php </span><span style="color: #007700">endwhile; </span><span style="color: #0000BB">?>
</span>            </ul>
        <span style="color: #0000BB"><?php </span><span style="color: #007700">echo </span><span style="color: #0000BB">$after_widget</span><span style="color: #007700">; </span><span style="color: #0000BB">?>
<?php
        wp_reset_query</span><span style="color: #007700">();  </span><span style="color: #FF8000">// Restore global post data stomped by the_post().
    </span><span style="color: #007700">endif;

    if ( </span><span style="color: #DD0000">'%BEG_OF_TITLE%' </span><span style="color: #007700">!= </span><span style="color: #0000BB">$args</span><span style="color: #007700">[</span><span style="color: #DD0000">'before_title'</span><span style="color: #007700">] )
        </span><span style="color: #0000BB">wp_cache_add</span><span style="color: #007700">(</span><span style="color: #DD0000">'widget_recent_entries'</span><span style="color: #007700">, </span><span style="color: #0000BB">ob_get_flush</span><span style="color: #007700">(), </span><span style="color: #DD0000">'widget'</span><span style="color: #007700">);
}
</span><span style="color: #0000BB">?></span></code>

Notes

  • This function uses PHP function style parameters.
  • wp_cache_add() is a wrapper that calls $wp_object_cache->add(...). See the WP_Object_Cache::add() function code for details on how this code operates.

See Also


Limitations While Creating This Document

  • A rule in the Codex's CSS prevents DIVs from being styled. I worked around this by using SPANs with a display of block.
  • The CSS rules don't have any padding for table elements. The only way to work around this (due to not being able to define CSS rules other than via individual style declarations) is by either using cellspacing and cellpadding (not desirable) or adding style information to every TH and TD element (also not desirable).
  • Lack of styling for DD and DT elements. I solved this by manually applying style information to each element.
  • The </dd> and </dt> elements are not supported, thus breaking standards.
  • The %%% directive makes very nicely-colored PHP code output, but it has limitations.
    • To get the output to be have syntax highlighting, it needs to be wrapped in <?php ?> tags. This adds unnecessary lines since the presence of these tags can be assumed in most instances. It would be nice if there could be an option to force highlighting without the use of the tags.
    • The output contains large amounts of whitespace at the top and bottom.
    • The output is not contained in a box like as the CSS styles the PRE. This type of container is helpful as it clearly sets the code apart from the rest of the documentation. I manually applied this look using the styled SPAN that I used for the function structure.
Retrieved from "https://codex.wordpress.org/index.php?title=User:Chrisbliss18/wp_cache_add&oldid=113136"

Codex Resources