Skip to main content

Yoast SEO: Metadata API

For simple websites, or when SEO is not a serious consideration, it's common for plugins and themes to simply output or echo meta tags into the <head> of a document.

However, more advanced SEO often requires meta tags to have context, an awareness of the other meta tags on a page, or complicated internal logic. For example, the value of a canonical URL tag might be influenced by the presence or value of a meta robots tag. For sites running complex or multiple plugins and themes, it's also important to consider standardization and security. Managing these kinds of challenges becomes increasingly cumbersome without a framework.

That's why we provide a formal way of managing the construction and output of meta tags in the <head> of each page. We use a presenter (an extension of the Abstract_Indexable_Presenter class) for each tag, which you can easily modify or extend.

Available presenters

By default, Yoast SEO ships with the following presenters that output meta tags.

Generic presenters

PresenterTag formatFilter
Title_Presenter<title>%s</title>wpseo_title
Meta_Description_Presenter<meta name="description" content="%s" />wpseo_metadesc
Canonical_Presenter<link rel="canonical" href="%s" />wpseo_canonical
Robots_Presenter<meta name="robots" content="%s" />wpseo_robots
Meta_Author_Presenter<meta name="author" content="%s" />wpseo_meta_author

Webmaster presenters

PresenterTag formatFilter
Baidu_Presenter<meta name="baidu-site-verification" content="%s" />n/a
Bing_Presenter<meta name="msvalidate.01" content="%s" />n/a
Google_Presenter<meta name="google-site-verification" content="%s" />n/a
Pinterest_Presenter<meta name="p:domain_verify" content="%s" />n/a
Yandex_Presenter<meta name="yandex-verification" content="%s" />n/a

Twitter presenters

PresenterTag formatFilter
Creator_Presenter<meta name="twitter:creator" content="%s" />n/a
Description_Presenter<meta name="twitter:description" content="%s" />wpseo_twitter_description
Image_Presenter<meta name="twitter:image" content="%s" />wpseo_twitter_image
Site_Presenter<meta name="twitter:site" content="%s" />wpseo_twitter_site
Title_Presenter<meta name="twitter:title" content="%s" />wpseo_twitter_title

OpenGraph presenters

PresenterTag formatFilter
Article_Author_Presenter<meta property="article:author" content="%s" />wpseo_opengraph_author_facebook
Article_Modified_Time_Presenter<meta property="article:modified_time" content="%s" />n/a
Article_Published_Time_Presenter<meta property="article:published_time" content="%s" />n/a
Article_Publisher_Presenter<meta property="article:publisher" content="%s" />wpseo_og_article_publisher
Description_Presenter<meta property="og:description" content="%s" />wpseo_opengraph_desc
Locale_Presenter<meta property="og:locale" content="%s" />wpseo_og_locale
Site_Name_Presenter<meta property="og:site_name" content="%s" />wpseo_opengraph_site_name
Title_Presenter<meta property="og:title" content="%s" />wpseo_opengraph_title
Type_Presenter<meta property="og:type" content="%s" />wpseo_opengraph_type
Url_Presenter<meta property="og:url" content="%s" />wpseo_opengraph_url
Image_Presenter<meta property="og:image" content="%s" />wpseo_opengraph_image

Deprecated Presenters

PresenterTag formatFilterDeprecated from
Googlebot_Presenter<meta name="googlebot" content="%s" />wpseo_googlebot
Bingbot_Presenter<meta name="bingbot" content="%s" />wpseo_bingbot
FB_App_ID_Presenter<meta property="fb:app_id" content="%s" />Yoast SEO 15.5 (Dec 2020)

Editing existing meta tags

Sometimes you might run into a situation where you want to edit the output of one of the meta tags which are output by Yoast SEO. To achieve this, Metadata Presenters you should use the relevant filter for the presenter in question.

Notes on using presenters and filters

  • All these filters expect a string to be returned.
  • Some presenters don't have an associated filter; typically where it makes more sense to programmatically alter the values of the post/page in question (such as with Article_Published_Time_Presenter).

Legacy filters

Please note These filters will be subject to change in the future as they are not yet represented through a Presenter class.

FilterDescription
wpseo_opengraph_image_sizeFilter to manipulate the image size used for Open Graph sharing.
- Only use this filter if you manually want to determine the custom image size for the og:image tag.
The size is either a string value (i.e. thumbnail) or an array of width/height values
(i.e. [ 200, 100 ]).
- The image will still be rejected if it is smaller than the size in the filter.
- If used, the size will always be enforced when saving a new feature image or updating a post with a feature image.
- Reindex the site if you want to apply the size to posts created before using the filter.
- You can do this with the command: wp yoast index --reindex. See Yoast SEO WP CLI: Reindex. Or you can install Yoast Test Helper to reset indexables.
- If the site was never indexed, then just go to Yoast SEO->Tools and click on Start SEO data optimization.

Examples

Below you will find a variety of examples that demonstrate some filters we provide.

Manipulate the meta robots tag output

/**
* Changes the max-video-preview to 100.
*
* @param string $output The string representation of the original output string.
* @param object $presentation The presentation object containing the necessary data.
*
* @return string The Googlebot meta tag.
*/
function change_robots_video_preview_settings( $output, $presentation ) {
$robots = $presentation->robots;

$values = \array_map( function( $item ) {
if ( strpos( $item, 'max-video-preview' ) !== false ) {
$item = 'max-video-preview:100';
}

return $item;
}, $robots );

return \implode( ', ', $values );
}

add_filter( 'wpseo_robots', 'change_robots_video_preview_settings', 10, 2 );

Appending a string to a category's title

/**
* Changes title for a specific category.
*
* @param string $title The current title.
* @param object $presentation The presentation object containing the necessary data.
*
* @return string The altered title tag.
*/
function change_category_title( $title, $presentation ) {
$categories = \get_the_category( $presentation->model->object_id );

foreach ( $categories as $category ) {
if ( $category->slug === 'books' ) {
return sprintf( '%s - %s', $title, $category->name );
}

return $title;
}
}

add_filter( 'wpseo_title', 'change_category_title', 10, 2 );

Adding meta tags

Adding your own meta tag(s) is as simple as creating your own class which extends Abstract_Indexable_Presenter. To get started, you'll need to understand the following:

  • Each implementation of Abstract_Indexable_Presenter must implement the two functions: get and present.

    • The get function should return the raw value of your meta (usually whatever is in the content property of the meta tag).
    • The present function should return the full meta tag.
  • Every Abstract_Indexable_Presenter class has 3 public properties, helpers, replace_vars and the presentation. You can use these to gather all data you need:

    • The helpers property currently includes all our helper classes which you can use to, for example, determine whether or not something is an article post type in regards to schema, using $this->helpers->schema->article->is_article_post_type( $post_type ).
    • The replace_vars property ensures you can use the $this->replace_vars( $string ) function to make use of our replacement variables in your own string if so desired.
    • The presentation contains all data that Yoast SEO puts out. Your IDE should make it easy for you to find the values you need.

Combined, this should lead to code that looks something like this:

use Yoast\WP\SEO\Presenters\Abstract_Indexable_Presenter;

/**
* Adds a custom my_meta_tag tag.
*/
class My_Custom_Presenter extends Abstract_Indexable_Presenter {
/**
* This output the full meta tag you want to add.
*/
public function present() {
return '<meta name="my_meta_tag" content="' . esc_attr( $this->get() ) . '" />';
}

/**
* Returns the value of our new tag.
*
* @return string The value of our meta tag.
*/
public function get() {
return ( $this->presentation->open_graph_locale === 'nl_NL' ) ? 'Dutch' : 'Not dutch';
}
}

For simple tags, you can use Abstract_Indexable_Tag_Presenter, which simply defines the string format and variable placeholder for the tag. A simple example would look like this:

use Yoast\WP\SEO\Presenters\Abstract_Indexable_Tag_Presenter;

/**
* Adds a custom my_meta_tag tag.
*/
class My_Custom_Presenter extends Abstract_Indexable_Tag_Presenter {

/**
* The tag format including placeholders.
*
* @var string
*/
protected $tag_format = '<meta name="my_meta_tag" content="%s" />';

/**
* Returns the value of our new tag.
*
* @return string The value of our meta tag.
*/
public function get() {
return ( $this->presentation->open_graph_locale === 'nl_NL' ) ? 'Dutch' : 'Not dutch';
}
}

This simpler format requires you to specify your tag format and replace where your value should be with %s, as it will be sprintf'ed to that position. This assumes that your get function returns a value that needs attribute escaping. If it's in fact a URL, you could change the escaping logic by setting the $escaping class attribute of your presenter to 'url'.

Because Abstract_Indexable_Tag_Presenter is itself inherited from Abstract_Indexable_Presenter all the tools you have there are available here too.

Registering your presenter

Regardless of which of the above methods you choose, you can then register your presenter through a filter:

/**
* Adds our custom presenter to the array of presenters.
*
* @param array $presenters The current array of presenters.
*
* @return array Presenters with our custom presenter added.
*/
function add_my_custom_presenter( $presenters ) {
$presenters[] = new My_Custom_Presenter();

return $presenters;
}

add_filter( 'wpseo_frontend_presenters', 'add_my_custom_presenter' );

Removing meta tags

Removing meta tags can be done by using the wpseo_frontend_presenters filter. In the following example, we'll remove the canonical URL presenter from the list.

/**
* Removes the canonical URL from the presenters.
*
* @param array $presenters The registered presenters.
*
* @return array The remaining presenters.
*/
function remove_canonical_presenter( $presenters ) {
return array_map( function( $presenter ) {
if ( ! $presenter instanceof Canonical_Presenter ) {
return $presenter;
}
}, $presenters );
}

add_action( 'wpseo_frontend_presenters', 'remove_canonical_presenter' );