class-subtitles.php

<?php
/**
 * @package Subtitles
 */

/**
 * Do not load this file directly
 *
 * @since 1.0.0
 */
if ( ! defined( 'ABSPATH' ) ) {
	die( '-1' );
}

/**
 * Checks for the existence of Subtitles before defining it.
 *
 * @link http://www.php.net//manual/en/function.class-exists.php
 *
 * @since 1.0.0
 */
if ( ! class_exists( 'Subtitles' ) ) {
	/**
	 * Define primary Subtitles class.
	 *
	 * Within classes constants and variables are called properties.
	 * Within classes functions are called methods.
	 *
	 * @link http://php.net/manual/en/language.oop5.php
	 *
	 * @since 1.0.0
	 */
	class Subtitles {
		/**
		 * Constant used for plugin versioning and enqueues.
		 *
		 * Constants differ from normal variables in that you don't use the $ symbol
		 * to declare or use them. The value must be a constant expression, not (for example)
		 * a variable, a property, a result of a mathematical operation, or a function call.
		 *
		 * Semantic versioning is used in this plugin.
		 *
		 * @link http://semver.org/
		 *
		 * @since 1.0.0
		 */
		const VERSION = '4.0.0';

		/**
		 * Constant used when referencing the plugin in load text domain calls and other
		 * functionality that relies on the slug of the plugin being present.
		 *
		 * @since 1.0.0
		 */
		const PLUGIN_SLUG = 'subtitles';

		/**
		 * Constant used in subtitle support checks for custom post types.
		 *
		 * @link http://codex.wordpress.org/Post_Types
		 *
		 * @since 1.0.0
		 */
		const SUBTITLE_FEATURE_SUPPORT = 'subtitles';

		/**
		 * Constant used in nonce checks when saving custom subtitles data.
		 *
		 * @link http://codex.wordpress.org/WordPress_Nonces
		 *
		 * @since 1.0.0
		 */
		const SUBTITLE_NONCE_NAME = '_subtitle_data_nonce';

		/**
		 * Constant used for subtitle meta key.
		 *
		 * Note the underscore before the custom meta for subtitles. This ensures that
		 * the meta key doesn't appear in the custom fields section on the new post
		 * and page screens and is only used within our classes. This is considered
		 * protected meta.
		 *
		 * @link http://codex.wordpress.org/Custom_Fields
		 *
		 * @since 1.0.0
		 */
		const SUBTITLE_META_KEY = '_subtitle';

		/**
		 * If no instance of Subtitles has been made then let's make it.
		 *
		 * Declaring class properties or methods as static makes them accessible
		 * without needing an instantiation of the class Subtitles.
		 *
		 * For example, this is how you would access a static property:
		 * Subtitles::$instance
		 *
		 * And this is how you would access a static method:
		 * Subtitles::getinstance()
		 *
		 * @link http://www.php.net/manual/en/language.oop5.late-static-bindings.php
		 * @var object $instance
		 * @access private
		 * @static
		 *
		 * @since 1.0.0
		 */
		private static $instance = null;

		/**
		 * Kick off the class if it hasn't been instantiated.
		 *
		 * There is a lot of information about the Singleton design pattern
		 * and singleton implementations for WordPress and plugins. I am not (at all!)
		 * an expert on this and may very well be instantiating Subtitles in the
		 * wrong way. If there's a better way to do this, or if it's not necessary
		 * to use this design pattern with the plugin, please let me know. The reason
		 * I've done it this way is because plugins should never be instantiated twice
		 * in WordPress. In general, I assume that this won't happen under normal circumstances,
		 * but using this design pattern ensures that if someone tries to instantiate
		 * Subtitles twice, then it won't be possible to do so.
		 *
		 * For more reading, see the following links.
		 *
		 * @link http://en.wikipedia.org/wiki/Singleton_pattern
		 * @link http://hardcorewp.com/2013/using-singleton-classes-for-wordpress-plugins/
		 * @link http://eamann.com/tech/the-case-for-singletons/
		 * @link http://www.toppa.com/2013/the-case-against-singletons-in-wordpress/
		 * @link http://eamann.com/tech/making-singletons-safe-in-php/
		 *
		 * @staticvar Singleton $instance The Singleton instance of this class.
		 * @return Singleton The Singleton instance of this class.
		 * @access public
		 * @static
		 *
		 * @since 1.0.0
		 */
		public static function getinstance() {
			if ( ! self::$instance ) {
				self::$instance = new Subtitles;
			}

			return self::$instance;
		} // end method getinstance

		/**
		 * Declare constructor methods for the class Subtitles.
		 *
		 * Classes which have a constructor method call this method on each newly-created object,
		 * so it is suitable for any initialization that the object may need before it is used.
		 *
		 * Access is set to protected to prevent outside access to the method for anything other than
		 * the class or a child class. Otherwise `new` could be used to kick off this constructor if
		 * it were public.
		 *
		 * @access protected
		 *
		 * @since 1.0.0
		 */
		protected function __construct() {
			/**
			 * Add default support for subtitles on posts and pages.
			 *
			 * To find out the number and name of arguments for any action in WordPress,
			 * search Core for the matching do_action call. For example, searching for
			 * "do_action( 'save_post'" reveals that two arguments, $post_id and $post are used.
			 *
			 * add_action accepts:
			 *
			 * - $tag The name of the action to which the $function_to_add is hooked.
			 * - callback function The name of the function you wish to be called.
			 * - int $priority optional. Used to specify the order in which the functions
			 *   associated with a particular action are executed (default: 10).
			 *   Lower numbers correspond with earlier execution, and functions with the
			 *   same priority are executed in the order in which they were added to the action.
			 * - int $accepted_args optional. The number of arguments the function accept (default: 1).
			 *
			 * Support for post types needs to be fired on `init`.
			 *
			 * @see add_action()
			 * @link http://codex.wordpress.org/Function_Reference/add_action
			 *
			 * @since 1.0.0
			 */
			add_action( 'init', array( &$this, 'add_subtitles_support' ) );

			/**
			 * Make Subtitles available for translation.
			 *
			 * Translations can be added into the /languages/ directory.
			 * @link http://codex.wordpress.org/Translating_WordPress
			 *
			 * @since 1.0.0
			 */
			add_action( 'init', array( &$this, 'load_subtitles_textdomain' ) );

			/**
			 * Output front-end styles for Subtitles via wp_head
			 *
			 * @see add_action()
			 * @since 2.0.0
			 */
			add_action( 'wp_head', array( &$this, 'subtitle_styling' ) );

			/**
			 * Filter post titles to display subtitles properly.
			 *
			 * add_filter accepts:
			 *
			 * - $tag             The name of the filter to hook the $function_to_add callback to.
			 * - $function_to_add The callback to be run when the filter is applied.
			 * - $priority        (optional) The order in which the functions associated with a
			 *                    particular action are executed. Lower numbers correspond with
			 *                    earlier execution, and functions with the same priority are
			 *                    executed in the order in which they were added to the action.
			 *                    Default: 10.
			 * $accepted_args     (optional) The number of arguments the function accepts.
			 *                    Default: 1.
			 *
			 * @see add_filter()
			 * @link http://codex.wordpress.org/Function_Reference/add_filter
			 *
			 * @since 1.0.0
			 */
			if ( ! is_admin() ) { // Don't touch anything inside of the WordPress Dashboard, yet.
				add_filter( 'the_title', array( &$this, 'the_subtitle' ), 10, 2 );

				/**
				 * Let's also filter the dedicated function for single post titles
				 *
				 * @link https://github.com/wecobble/Subtitles/issues/2
				 *
				 * @since 1.0.1
				 */
				add_filter( 'single_post_title', array( &$this, 'the_subtitle' ), 10, 2 );

				/**
				 * Make sure that Subtitles plays nice with WordPress SEO plugin by Yoast
				 *
				 * @link https://wordpress.org/plugins/wordpress-seo/
				 * @link https://github.com/wecobble/Subtitles/issues/5
				 *
				 * @since 1.0.1
				 * @since 4.0.0 - Deprecate the wp_seo_get_bc_title filter and use
				 *                wpseo_breadcrumb_single_link_info instead.
				 *                See https://yoast.com/yoast-seo-5-8/
				 */
				add_filter( 'wpseo_breadcrumb_single_link_info', array( &$this, 'plugin_compat_wordpress_seo' ) );
			}
		} // end method __construct

		/**
		 * Make sure that Subtitles plays nice with WordPress SEO plugin by Yoast.
		 *
		 * The plugin features breadcrumb functionality, which users can add into their themes
		 * by using functionality that's specific to the plugin. Because it's so popular and
		 * I'm not sure where or how people will insert their breadcrumbs into their template
		 * files, it's best avoid messing with the plugin altogether. We'll filter the output
		 * and make sure that subtitles isn't included in any of the breadcrumb titles.
		 *
		 * @link https://wordpress.org/plugins/wordpress-seo/
		 * @link https://github.com/wecobble/Subtitles/issues/5
		 * @link http://us1.php.net//manual/en/function.strlen.php
		 * @see get_the_subtitle()
		 *
		 * @since 1.0.1
		 */
		public function plugin_compat_wordpress_seo( $breadcrumb_text ) {
			/**
			 * This issue only arrises when breadcrumbs are placed inside of The Loop,
			 * so we'll first check to see if we're in The Loop, and if not, just bail
			 * on this altogether.
			 *
			 * @link http://codex.wordpress.org/Function_Reference/in_the_loop
			 *
			 * @since 1.0.1
			 */
			$in_the_loop = (bool) in_the_loop();
			if ( ! $in_the_loop ) {
				return $breadcrumb_text;
			}

			/**
			 * Grab the post subtitle.
			 *
			 * Example: (string) "Subtitle"
			 *
			 * @see get_the_subtitle()
			 *
			 * @since 1.0.1
			 */
			$post_subtitle = get_the_subtitle();

			/**
			 * Grab the length of the post subtitle.
			 *
			 * We're also using a negative value of the legnth of the subtitle.
			 *
			 * Example: (int) 8
			 *
			 * @link http://us1.php.net//manual/en/function.strlen.php
			 *
			 * @since 1.0.1
			 */
			$post_subtitle_length = (int) strlen( $post_subtitle );
			$post_subtitle_length_neg = -1 * $post_subtitle_length;

			/**
			 * Grab the already filtered post title.
			 *
			 * Example: (string) "Post TitleSubtitle"
			 */
			$post_title = (string) $breadcrumb_text['text'];

			/**
			 * Grab the length of the filtered post title.
			 *
			 * Example: (int) 18
			 */
			$post_title_length = (int) strlen( $post_title );

			/**
			 * Check for a few specific cases:
			 *
			 * 1. Does the subtitle of the current post equal the title of any of its ancestors?
			 * 2. Is the post title that's being checked empty?
			 *
			 * If so, then bail out on this.
			 *
			 * Example: If the subtitle of the page is "Features" and one of the parent breadcrumbs also
			 * has the name "Features", then we don't want to mess that up, so we'll make sure that we bail out
			 * early on this function.
			 *
			 * @since 1.0.1
			 */
			if ( ( $post_title == $post_subtitle ) || ( '' == $post_title ) ) {
				return $breadcrumb_text;
			}

			/**
			 * Remove the subtitle from the "title" string so that it shows up properly.
			 *
			 * Example: If the post title that we've brought into the function is called "Post TitleSubtitle",
			 * then all we really want is the the title to say "Post Title", so we'll use the length of the subtitle
			 * to cut that many characters off of the end of the post title, and hope to end up with "Post Title".
			 *
			 * @see apply_filters()
			 * @link http://us2.php.net//manual/en/function.substr.php
			 *
			 * @since 1.0.1
			 */
			$post_title = substr( $post_title, 0, $post_subtitle_length_neg );
			$post_title = apply_filters( 'compat_wordpress_seo', $post_title );

			/**
			 * Make sure that the new title and its subtitle is the right string that
			 * we want to manipulate, by comparing the post title + subtitle against
			 * the original title that we brought into this function.
			 *
			 * Example: The original title brought in was "Post TitleSubtitle", so we'll
			 * make sure that "Post Title" + "Subtitle" is actually "Post TitleSubtitle".
			 *
			 * @since 1.0.1
			 */
			$reconstructed_title = $post_title . $post_subtitle;

			if ( $reconstructed_title == $breadcrumb_text['text'] ) {
				$breadcrumb_text['text'] = $post_title;
				return $breadcrumb_text;
			}

			// else just return the title that was brought into the function
			return $breadcrumb_text;
		} // end plugin_compat_wordpress_seo()

		/**
		 * Add default support for subtitles on posts and pages.
		 *
		 * @since 1.0.0
		 */
		public function add_subtitles_support() {
			/**
			 * Automatically enable subtitles support on posts.
			 *
			 * This can be overridden within themes.
			 *
			 * @see add_post_type_support()
			 * @link http://codex.wordpress.org/Function_Reference/add_post_type_support
			 * @see SUBTITLE_FEATURE_SUPPORT
			 *
			 * @since 1.0.0
			 */
			add_post_type_support( 'post', self::SUBTITLE_FEATURE_SUPPORT );

			/**
			 * Automatically enable subtitles support on pages.
			 *
			 * This can be overridden within themes.
			 *
			 * @see add_post_type_support()
			 * @link http://codex.wordpress.org/Function_Reference/add_post_type_support
			 * @see SUBTITLE_FEATURE_SUPPORT
			 *
			 * @since 1.0.0
			 */
			add_post_type_support( 'page', self::SUBTITLE_FEATURE_SUPPORT );

			/**
			 * Automatically enable subtitles support for Jetpack Portfolios
			 *
			 * This can be overridden within themes.
			 *
			 * @see  add_post_type_support()
			 * @link http://codex.wordpress.org/Function_Reference/add_post_type_support
			 * @link https://jetpack.com/support/custom-content-types/
			 * @see  SUBTITLE_FEATURE_SUPPORT
			 *
			 * @since 1.0.7
			 */
			add_post_type_support( 'jetpack-portfolio', self::SUBTITLE_FEATURE_SUPPORT );

			/**
			 * Automatically enable subtitles support for Jetpack Testimonials
			 *
			 * This can be overridden within themes.
			 *
			 * @see  add_post_type_support()
			 * @link http://codex.wordpress.org/Function_Reference/add_post_type_support
			 * @link https://jetpack.com/support/custom-content-types/
			 * @see  SUBTITLE_FEATURE_SUPPORT
			 *
			 * @since 2.2.0
			 */
			add_post_type_support( 'jetpack-testimonial', self::SUBTITLE_FEATURE_SUPPORT );
		} // end add_subtitles_support()

		/**
		 * Declare __clone as private to prevent cloning an instance of the class via `clone`.
		 *
		 * @link http://www.php.net/manual/en/language.oop5.cloning.php
		 * @access protected
		 *
		 * @since 1.0.0
		 */
		protected function __clone() {

		} // end method __clone()

		/**
		 * Prevent unserializing.
		 *
		 * @link http://php.net/function.unserialize
		 * @access public
		 *
		 * @since 1.0.0
		 */
		public function __wakeup() {
			// i18n won't work on this exception so there's no need to add it into the language pack
			throw new Exception( 'This Singleton cannot be unserialized.' );
		} // end method __wakeup()

		/**
		 * Make Subtitles available for translation.
		 *
		 * @link https://ulrich.pogson.ch/load-theme-plugin-translations
		 * @link http://ottopress.com/2013/language-packs-101-prepwork/
		 *
		 * @since 1.0.0
		 */
		public function load_subtitles_textdomain() {
			$domain = self::PLUGIN_SLUG;
			$locale = apply_filters( 'plugin_locale', get_locale(), $domain );

			/**
			 * Load a .mo file into the text domain $domain.
			 *
			 * If the text domain already exists, the translations will be merged. If both
			 * sets have the same string, the translation from the original value will be taken.
			 *
			 * On success, the .mo file will be placed in the $l10n global by $domain
			 * and will be a MO object.
			 *
			 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
			 * @param string $mofile Path to the .mo file.
			 * @return bool  True on success, false on failure.
			 *
			 * @since 1.0.0
			 */
			load_textdomain( $domain, trailingslashit( WP_LANG_DIR ) . $domain . '/' . $domain . '-' . $locale . '.mo' );

			/**
			 * Load a plugin's translated strings.
			 *
			 * If the path is not given then it will be the root of the plugin directory.
			 *
			 * The .mo file should be named based on the text domain with a dash, and then the locale exactly.
			 *
			 * @param string $domain          Unique identifier for retrieving translated strings
			 * @param string $deprecated      Use the $plugin_rel_path parameter instead.
			 * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.
			 *
			 * @since 1.0.0
			 */
			load_plugin_textdomain( $domain, false, basename( plugin_dir_path( dirname( __FILE__ ) ) ) . '/languages/' );
		}

		/**
		 * Output front-end styles for Subtitles via wp_head
		 *
		 * @access public
		 * @since  2.0.0
		 */
		public function subtitle_styling() {
	?>
			<style type="text/css" media="screen">
				/**
				 * Plugin Name: Subtitles
				 * Plugin URI: http://wordpress.org/plugins/subtitles/
				 * Description: Easily add subtitles into your WordPress posts, pages, custom post types, and themes.
				 * Author: <a href="https://philip.blog/">Philip Arthur Moore</a>, <a href="https://wecobble.com">We Cobble</a>
				 * Author URI: https://wecobble.com/
				 * Version: 4.0.0
				 * License: GNU General Public License v2 or later
				 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
				 */

				/**
				 * Be explicit about this styling only applying to spans,
				 * since that's the default markup that's returned by
				 * Subtitles. If a developer overrides the default subtitles
				 * markup with another element or class, we don't want to stomp
				 * on that.
				 *
				 * @since 1.0.0
				 */
				span.entry-subtitle {
					display: block; /* Put subtitles on their own line by default. */
					font-size: 0.53333333333333em; /* Sensible scaling. It's assumed that post titles will be wrapped in heading tags. */
				}
				/**
				 * If subtitles are shown in comment areas, we'll hide them by default.
				 *
				 * @since 1.0.5
				 */
				#comments .comments-title span.entry-subtitle {
					display: none;
				}
			</style><?php
		} // end function subtitle_styling

		/**
		 * Output the subtitle
		 *
		 * @since 1.0.0
		 */
		public function the_subtitle( $title, $id = null ) {
			/**
			 * Which globals will we need?
			 *
			 * @since 1.0.0
			 */
			global $post;

			/**
			 * Check if $post is set. There's a chance that this can
			 * be NULL on search results pages with zero results.
			 *
			 * @link https://github.com/wecobble/Subtitles/issues/12
			 *
			 * @since 1.0.2
			 */
			if ( ! isset( $post ) ) {
				return $title;
			}

			/**
			 * Make sure we're not touching any of the titles in the Dashboard
			 * This filtering should only happen on the front end of the site.
			 *
			 * @since 1.0.0
			 */
			if ( is_admin() ) {
				return $title;
			}

			/**
			 * Do not show subtitles in RSS feeds, but give devs. the option
			 * to turn this off.
			 *
			 * @since 2.0.1
			 */
			$is_feed = apply_filters( 'subtitles_is_feed', is_feed() );
			if ( $is_feed ) {
				return $title;
			}

			/**
			 * Bail early if no subtitle has been set for the post.
			 *
			 * @since 1.0.0
			 */
			$post_id = (int) absint( $post->ID ); // post ID should always be a non-negative integer
			$subtitle = (string) html_entity_decode( wp_unslash( esc_html( get_post_meta( $post_id, self::SUBTITLE_META_KEY, true ) ) ), ENT_QUOTES );

			/**
			 * Allow theme and plugin authors to override the early return if no subtitle exists.
			 *
			 * @see   https://github.com/wecobble/Subtitles/issues/79
			 * @since 2.2.0
			 */
			$subtitle_exists = ! empty( $subtitle );
			$subtitle_exists = apply_filters( 'subtitle_exists',  $subtitle_exists );

			if ( ! $subtitle_exists ) {
				return $title;
			}

			/**
			 * Bail if the title being filtered isn't the actual primary post title.
			 *
			 * This can happen when something is used within the loop that outputs titles,
			 * like navigation between single posts on a blog.
			 *
			 * $id should not be an object, and if it is then the single_post_title() filter is likely
			 * being invoked, so we'll need a check against that.
			 *
			 * Here's a more detailed explanation:
			 *
			 * 1. the_title() can be filtered with apply_filters( 'the_title', $title, $id ).
			 *    This means that the second argument needs to be an integer, which will be the ID of a post.
			 * 2. single_post_title() can be filtered with apply_filters( 'single_post_title', $_post->post_title, $_post ).
			 *    This means that the second argument needs to be the entire post object.
			 *
			 * So if we're checking $id and it's an object, then there's a good chance that single_post_title()
			 * is being used and we need to reassign $id to be ID of the object WP_Post.
			 *
			 * @see the_title()
			 * @see single_post_title()
			 * @see get_the_ID()
			 * @see is_object()
			 *
			 * @since 1.0.0
			 */
			if ( isset( $id ) && is_object( $id ) ) { // single_post_title() is being used.
				$id = $id->ID; // grab the ID from the post object.
			}
			if ( isset( $post->post_title ) && get_the_ID() != $id ) {
				return $title;
			}

			/**
			 * Make sure we're in The Loop. If a theme maker wants to create
			 * a custom loop via WP_Query, then he can filter subtitle_view_supported.
			 *
			 * @see in_the_loop()
			 * @link http://codex.wordpress.org/Function_Reference/in_the_loop
			 *
			 * @since 1.0.0
			 */
			$subtitle_view_supported = true;

			$in_the_loop = (bool) in_the_loop();
			if ( ! $in_the_loop ) {
				$subtitle_view_supported = false;
			}

			/**
			 * Allow subtitle views to be filtered by theme developers.
			 *
			 * @see apply_filters()
			 * @link http://codex.wordpress.org/Function_Reference/apply_filters
			 *
			 * @since 1.0.0
			 */
			$subtitle_view_supported = (bool) apply_filters( 'subtitle_view_supported', $subtitle_view_supported );

			/**
			 * If no subtitle support is active for the given view
			 * then simply return the post title.
			 *
			 * @since 1.0.0
			 */
			if ( ! $subtitle_view_supported ) {
				return $title;
			}

			/**
			 * Bail if the current post type doesn't support Subtitles.
			 *
			 * The good news here is that if Subtitles have been entered in for a user,
			 * but support for a specific post type has been removed, then the subtitles
			 * won't be displayed on the front-end of the site but will still be retained
			 * in the database. This is useful for child themes and such who want to override
			 * the look and feel of a theme that features subtitles.
			 *
			 * @since 1.0.0
			 */
			if ( ! post_type_supports( $post->post_type, self::SUBTITLE_FEATURE_SUPPORT ) ) {
				return $title;
			}

			/**
			 * Let theme authors modify the subtitle markup, in case spans aren't appropriate
			 * for what they are trying to do with their themes.
			 *
			 * The reason that spans are being used is because HTML does not have a dedicated
			 * mechanism for marking up subheadings, alternative titles, or taglines. There
			 * are suggested alternatives from the World Wide Web Consortium (W3C); among them
			 * are spans, which work well for what we're trying to do with titles in WordPress.
			 * See the linked documentation for more information.
			 *
			 * @link http://www.w3.org/html/wg/drafts/html/master/common-idioms.html#sub-head
			 *
			 * @since 1.0.0
			 */
			$subtitle_markup = apply_filters(
				'subtitle_markup',
				array(
					'before' => '<span class="entry-subtitle">',
					'after'  => '</span>',
				)
			);

			$subtitle = $subtitle_markup['before'] . $subtitle . $subtitle_markup['after'];

			/**
			 * Put together the final title and subtitle set
			 *
			 * @since 1.0.0
			 */
			$title = '<span class="entry-title-primary">' . $title . '</span> ' . $subtitle;

			/**
			 * Filter the post subtitle, if necessary.
			 *
			 * @param string $title The post title.
			 * @param int    $id    The post ID.
			 *
			 * @since 1.0.0
			 */
			return apply_filters( 'the_subtitle', $title );
		}

		/**
		 * Get the Subtitle.
		 *
		 * This is a helper method used to grab the subtitle for any given post,
		 * which theme authors can use with the template tag get_the_subtitle().
		 *
		 * @since 1.0.0
		 */
		public static function get_the_subtitle( $post = 0 ) {
			/**
			 * Bail early if no subtitle has been set for the post.
			 *
			 * @since 1.0.0
			 */
			$post = get_post( $post ); // this will be returned as an object or NULL
			$post_id = ( isset( $post ) ) ? $post->ID : 0; // post ID should always be a non-negative integer
			$subtitle = (string) html_entity_decode( wp_unslash( esc_html( get_post_meta( $post_id, self::SUBTITLE_META_KEY, true ) ) ), ENT_QUOTES );

			if ( '' === $subtitle ) {
				return $subtitle;
			}

			/**
			 * Filter the post subtitle.
			 *
			 * @since 1.0.0
			 *
			 * @param string $subtitle The post subtitle.
			 * @param int    $id    The post ID.
			 */
			return apply_filters( 'the_subtitle', $subtitle );
		} // end get_the_subtitle()
	} // end class Subtitles
} // End if().