Add option to use meta titles in breadcrumbs. Closes #704.

Introduces a new 'Use meta titles for breadcrumbs' setting and shortcode attribute, allowing users to choose between meta titles and page titles for breadcrumb output. Updates schema settings UI, translation files, and internal logic to support this feature. Also bumps plugin version to 5.1.4 and updates upgrade routines and notification messaging.

Author: sybrew

autodescription.php

@@ -16,7 +16,7 @@
  * Plugin Name: The SEO Framework
  * Plugin URI: https://theseoframework.com/
  * Description: An automated, advanced, accessible, unbranded and extremely fast SEO solution for your WordPress website.
- * Version: 5.1.3
+ * Version: 5.1.4
  * Author: Sybre Waaijer
  * Author URI: https://theseoframework.com/
  * License: GPLv3
@@ -53,7 +53,7 @@
  *
  * @since 2.3.5
  */
-define( 'THE_SEO_FRAMEWORK_VERSION', '5.1.3' );
+define( 'THE_SEO_FRAMEWORK_VERSION', '5.1.4' );
 
 /**
  * The plugin Database version.
@@ -62,7 +62,7 @@
  *
  * @since 2.7.0
  */
-define( 'THE_SEO_FRAMEWORK_DB_VERSION', '5130' );
+define( 'THE_SEO_FRAMEWORK_DB_VERSION', '5140' );
 
 /**
  * The plugin file, absolute unix path.

bootstrap/upgrade.php

@@ -216,7 +216,7 @@ function _upgrade( $previous_version ) {
 		'2701', '2802', '2900',
 		'3001', '3103', '3300',
 		'4051', '4103', '4110', '4200', '4270',
-		'5001', '5050', '5100', '5130',
+		'5001', '5050', '5100', '5130', '5140',
 	];
 	// phpcs:enable WordPress.Arrays.ArrayDeclarationSpacing.ArrayItemNoNewLine
 
@@ -1002,3 +1002,14 @@ function _do_upgrade_5130() {
 			'display_user_edit_options' => 1,
 		] );
 }
+
+/**
+ * Registers new option 'breadcrumb_use_meta_title'. Enabled for upgraded sites, disabled for new sites.
+ *
+ * @since 5.1.4
+ */
+function _do_upgrade_5140() {
+
+	if ( \get_option( 'the_seo_framework_initial_db_version' ) < '5140' )
+		Data\Plugin::update_option( 'breadcrumb_use_meta_title', 1 );
+}

inc/classes/admin/settings/plugin.class.php

@@ -764,4 +764,14 @@ public static function _schema_metabox_general_tab() {
 	public static function _schema_metabox_presence_tab() {
 		Template::output_view( 'settings/metaboxes/schema', 'presence' );
 	}
+
+	/**
+	 * Schema Meta Box Breadcrumbs Tab output.
+	 *
+	 * @since 5.1.4
+	 * @see self::schema_metabox() Callback for Schema.org Settings box.
+	 */
+	public static function _schema_metabox_breadcrumbs_tab() {
+		Template::output_view( 'settings/metaboxes/schema', 'breadcrumbs' );
+	}
 }

inc/classes/data/filter/plugin.class.php

@@ -150,17 +150,18 @@ public static function register_sanitizers_jit() {
 
 		$filters = [
 			'advanced_query_protection'    => 'checkbox',
-			'alter_archive_query'          => 'checkbox',
 			'alter_archive_query_type'     => 'alter_query_type',
+			'alter_archive_query'          => 'checkbox',
 			'alter_search_query_type'      => 'alter_query_type',
 			'alter_search_query'           => 'checkbox',
 			'author_noarchive'             => 'checkbox',
 			'author_nofollow'              => 'checkbox',
 			'author_noindex'               => 'checkbox',
-			'auto_description'             => 'checkbox',
 			'auto_description_html_method' => 'auto_description_method',
+			'auto_description'             => 'checkbox',
 			'baidu_verification'           => 'verification_code',
 			'bing_verification'            => 'verification_code',
+			'breadcrumb_use_meta_title'    => 'checkbox',
 			'cache_sitemap'                => 'checkbox',
 			'canonical_scheme'             => 'canonical_scheme',
 			'date_noarchive'               => 'checkbox',
@@ -171,25 +172,25 @@ public static function register_sanitizers_jit() {
 			'display_character_counter'    => 'checkbox',
 			'display_list_edit_options'    => 'checkbox',
 			'display_pixel_counter'        => 'checkbox',
-			'display_term_edit_options'    => 'checkbox',
-			'display_user_edit_options'    => 'checkbox',
 			'display_seo_bar_metabox'      => 'checkbox',
 			'display_seo_bar_tables'       => 'checkbox',
+			'display_term_edit_options'    => 'checkbox',
+			'display_user_edit_options'    => 'checkbox',
 			'excerpt_the_feed'             => 'checkbox',
 			'facebook_author'              => 'facebook_profile_link',
 			'facebook_publisher'           => 'facebook_profile_link',
 			'facebook_tags'                => 'checkbox',
 			'google_verification'          => 'verification_code',
 			'home_paged_noindex'           => 'checkbox',
 			'home_title_location'          => 'title_location',
+			'homepage_canonical'           => 'fully_qualified_url',
 			'homepage_description'         => 'metadata_text',
 			'homepage_noarchive'           => 'checkbox',
 			'homepage_nofollow'            => 'checkbox',
 			'homepage_noindex'             => 'checkbox',
-			'homepage_canonical'           => 'fully_qualified_url',
-			'homepage_redirect'            => 'fully_qualified_url',
 			'homepage_og_description'      => 'metadata_text',
 			'homepage_og_title'            => 'metadata_text',
+			'homepage_redirect'            => 'fully_qualified_url',
 			'homepage_social_image_id'     => 'absolute_integer',
 			'homepage_social_image_url'    => 'fully_qualified_url',
 			'homepage_tagline'             => 'checkbox',

inc/classes/data/plugin/setup.class.php

@@ -310,10 +310,11 @@ public static function get_default_options() {
 				'pint_verification'   => '', // Pinterest Verification Code.
 
 				// Schema.org.
-				'ld_json_enabled'        => 1, // LD+Json toggle for Schema.
-				'ld_json_searchbox'      => 1, // LD+Json Sitelinks Search Box.
-				'ld_json_breadcrumbs'    => 1, // LD+Json Breadcrumbs.
-				'knowledge_output'       => 1, // Default for outputting the Knowledge SEO.
+				'ld_json_enabled'           => 1, // LD+Json toggle for Schema.
+				'ld_json_searchbox'         => 1, // LD+Json Sitelinks Search Box.
+				'ld_json_breadcrumbs'       => 1, // LD+Json Breadcrumbs.
+				'breadcrumb_use_meta_title' => 0, // Whether to consider meta titles for breadcrumbs.
+				'knowledge_output'          => 1, // Default for outputting the Knowledge SEO.
 
 				// Knowledge general <https://developers.google.com/structured-data/customize/contact-points> - This is extremely extended and valuable. Expect a premium version.
 				'knowledge_type'   => 'organization', // Organization or Person, dropdown.

inc/classes/meta/breadcrumbs.class.php

@@ -47,54 +47,99 @@
  */
 class Breadcrumbs {
 
+	/**
+	 * @since 5.1.4
+	 * @var array The options for breadcrumb generation.
+	 */
+	private static $options = [];
+
 	/**
 	 * Returns a list of breadcrumbs by URL and name.
 	 *
 	 * @since 5.0.0
+	 * @since 5.1.4 Added the `$options` parameter.
 	 * @todo consider wp_force_plain_post_permalink()
-	 * @todo add extra parameter for $options; create (class?) constants for them.
-	 *       -> Is tsf()->breadcrumbs()::CONSTANT possible?
-	 *       -> Then, forward the options to a class variable, and build therefrom. Use as argument for memo().
+	 * @todo add extra parameters for $options?
 	 *       -> Requested features (for shortcode): Remove home, remove current page.
-	 *       -> Requested features (globally): Remove/show archive prefixes, hide PTA/terms, select home name, select SEO vs custom title (popular).
+	 *       -> Requested features (globally): Remove/show archive prefixes, hide PTA/terms, select home name.
 	 *       -> Add generation args to every crumb; this way we can perform custom lookups for titles after the crumb is generated.
 	 *
-	 * @param array|null $args The query arguments. Accepts 'id', 'tax', 'pta', and 'uid'.
-	 *                         Leave null to autodetermine query.
+	 * @param array|null $args    The query arguments. Accepts 'id', 'tax', 'pta', and 'uid'.
+	 *                            Leave null to autodetermine query.
+	 * @param array      $options Optional. {
+	 *     The options for breadcrumb generation
+	 *
+	 *     @type ?bool $use_meta_title Whether to consider meta titles before using page titles.
+	 *                                 Default determined by 'breadcrumb_use_meta_title' option.
+	 * }
 	 * @return array[] {
 	 *     The breadcrumb list items in order of appearance.
 	 *
 	 *     @type string $url  The breadcrumb URL.
 	 *     @type string $name The breadcrumb page title.
 	 * }
 	 */
-	public static function get_breadcrumb_list( $args = null ) {
+	public static function get_breadcrumb_list( $args = null, $options = [] ) {
+
+		// The default options must be ordered alphabetically to ensure consistent cache keys.
+		self::$options = array_merge(
+			[
+				'use_meta_title' => (bool) Data\Plugin::get_option( 'breadcrumb_use_meta_title' ),
+			],
+			array_filter(
+				$options,
+				fn( $v ) => null !== $v,
+			),
+		);
+
+		// Sort options alphabetically to ensure consistent cache keys regardless of input order.
+		ksort( self::$options );
 
 		if ( isset( $args ) ) {
 			normalize_generation_args( $args );
 			$list = self::get_breadcrumb_list_from_args( $args );
 		} else {
-			$list = memo() ?? memo( self::get_breadcrumb_list_from_query() );
+			$list = memo( null, self::$options ) ?? memo( self::get_breadcrumb_list_from_query(), self::$options );
 		}
 
 		/**
 		 * @since 5.0.0
+		 * @since 5.1.4 Added the `$options` parameter.
 		 * @param array[] {
 		 *     The breadcrumb list items in order of appearance.
 		 *
 		 *     @type string $url  The breadcrumb URL.
 		 *     @type string $name The breadcrumb page title.
 		 * }
-		 * @param array|null $args The query arguments. Contains 'id', 'tax', 'pta', and 'uid'.
-		 *                         Is null when the query is auto-determined.
+		 * @param array|null $args    The query arguments. Contains 'id', 'tax', 'pta', and 'uid'.
+		 *                            Is null when the query is auto-determined.
+		 * @param array      $options The options used for breadcrumb generation.
 		 */
 		return (array) \apply_filters(
 			'the_seo_framework_breadcrumb_list',
 			$list,
 			$args,
+			self::$options,
 		);
 	}
 
+	/**
+	 * Returns the breadcrumb title based on the current setting.
+	 *
+	 * @since 5.1.4
+	 *
+	 * @param array|null $args The query arguments. Accepts 'id', 'tax', 'pta', and 'uid'.
+	 *                         Leave null to autodetermine query.
+	 * @return string The breadcrumb title.
+	 */
+	private static function get_breadcrumb_title( $args = null ) {
+
+		if ( self::$options['use_meta_title'] )
+			return Meta\Title::get_bare_title( $args );
+
+		return Meta\Title::get_bare_generated_title( $args );
+	}
+
 	/**
 	 * Gets a list of breadcrumbs, based on expected or current query.
 	 *
@@ -216,7 +261,7 @@ private static function get_singular_breadcrumb_list( $id = null ) {
 		if ( \get_post_type_object( $post_type )->has_archive ?? false ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_pta_url( $post_type ),
-				'name' => Meta\Title::get_bare_title( [ 'pta' => $post_type ] ),
+				'name' => self::get_breadcrumb_title( [ 'pta' => $post_type ] ),
 			];
 		}
 
@@ -237,7 +282,7 @@ private static function get_singular_breadcrumb_list( $id = null ) {
 			) as $parent ) {
 				$crumbs[] = [
 					'url'  => Meta\URI::get_bare_term_url( $parent->term_id, $parent->taxonomy ),
-					'name' => Meta\Title::get_bare_title( [
+					'name' => self::get_breadcrumb_title( [
 						'id'  => $parent->term_id,
 						'tax' => $parent->taxonomy,
 					] ),
@@ -249,19 +294,19 @@ private static function get_singular_breadcrumb_list( $id = null ) {
 		foreach ( Data\Post::get_post_parents( $post->ID ) as $parent ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_singular_url( $parent->ID ),
-				'name' => Meta\Title::get_bare_title( [ 'id' => $parent->ID ] ),
+				'name' => self::get_breadcrumb_title( [ 'id' => $parent->ID ] ),
 			];
 		}
 
 		if ( isset( $id ) ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_singular_url( $post->ID ),
-				'name' => Meta\Title::get_bare_title( [ 'id' => $post->ID ] ),
+				'name' => self::get_breadcrumb_title( [ 'id' => $post->ID ] ),
 			];
 		} else {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_singular_url(),
-				'name' => Meta\Title::get_bare_title(),
+				'name' => self::get_breadcrumb_title(),
 			];
 		}
 
@@ -303,7 +348,7 @@ private static function get_term_breadcrumb_list( $term_id = null, $taxonomy = '
 		) as $parent ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_term_url( $parent->term_id, $parent->taxonomy ),
-				'name' => Meta\Title::get_bare_title( [
+				'name' => self::get_breadcrumb_title( [
 					'id'  => $parent->term_id,
 					'tax' => $parent->taxonomy,
 				] ),
@@ -313,15 +358,15 @@ private static function get_term_breadcrumb_list( $term_id = null, $taxonomy = '
 		if ( isset( $term_id ) ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_term_url( $term_id, $taxonomy ),
-				'name' => Meta\Title::get_bare_title( [
+				'name' => self::get_breadcrumb_title( [
 					'id'  => $term_id,
 					'tax' => $taxonomy,
 				] ),
 			];
 		} else {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_term_url(),
-				'name' => Meta\Title::get_bare_title(),
+				'name' => self::get_breadcrumb_title(),
 			];
 		}
 
@@ -352,12 +397,12 @@ private static function get_pta_breadcrumb_list( $post_type = null ) {
 		if ( isset( $post_type ) ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_pta_url( $post_type ),
-				'name' => Meta\Title::get_bare_title( [ 'pta' => $post_type ] ),
+				'name' => self::get_breadcrumb_title( [ 'pta' => $post_type ] ),
 			];
 		} else {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_pta_url(),
-				'name' => Meta\Title::get_bare_title(),
+				'name' => self::get_breadcrumb_title(),
 			];
 		}
 
@@ -387,12 +432,12 @@ private static function get_author_breadcrumb_list( $id = null ) {
 		if ( isset( $id ) ) {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_author_url( $id ),
-				'name' => Meta\Title::get_bare_title( [ 'uid' => $id ] ),
+				'name' => self::get_breadcrumb_title( [ 'uid' => $id ] ),
 			];
 		} else {
 			$crumbs[] = [
 				'url'  => Meta\URI::get_bare_author_url(),
-				'name' => Meta\Title::get_bare_title(),
+				'name' => self::get_breadcrumb_title(), // NOTE: has no meta title (yet), but we'll add that in 5.2.0
 			];
 		}
 
@@ -426,7 +471,7 @@ private static function get_date_breadcrumb_list() {
 					\get_query_var( 'monthnum' ),
 					\get_query_var( 'day' ),
 				),
-				'name' => Meta\Title::get_bare_title(),
+				'name' => Meta\Title::get_bare_generated_title(), // discrepancy, has no meta title
 			],
 		];
 	}
@@ -448,7 +493,7 @@ private static function get_search_breadcrumb_list() {
 			self::get_front_breadcrumb(),
 			[
 				'url'  => Meta\URI::get_search_url(),
-				'name' => Meta\Title::get_search_query_title(), // discrepancy
+				'name' => Meta\Title::get_search_query_title(), // discrepancy, has no meta title
 			],
 		];
 	}
@@ -470,7 +515,7 @@ private static function get_404_breadcrumb_list() {
 			self::get_front_breadcrumb(),
 			[
 				'url'  => '',
-				'name' => Meta\Title::get_404_title(), // discrepancy
+				'name' => Meta\Title::get_404_title(), // discrepancy, has no meta title
 			],
 		];
 	}
@@ -490,7 +535,7 @@ private static function get_404_breadcrumb_list() {
 	private static function get_front_breadcrumb() {
 		return [
 			'url'  => Meta\URI::get_bare_front_page_url(),
-			'name' => Meta\Title::get_front_page_title(), // discrepancy
+			'name' => Meta\Title::get_front_page_title(), // discrepancy, has no meta title
 		];
 	}
 }