Merge branch 'develop'

changelog.txt

@@ -1,3 +1,35 @@
+= 2.5.1 =
+* Enhancement
+    * Add ability to show the post date after the post title
+    * Allow getting post fields from the cache
+    * Add new filter to filter all related posts permalinks
+    * Add new tests for the post type feature (GitHub)
+* Bug fixes
+	* (minor) Add post classes after retrieving posts from the cache
+	* (minor) Return an error if invalid taxonomies or post types was requested with the WP Rest API
+
+= 2.5.0 =
+* Enhancement
+	* Prepare plugin for gutenberg blocks
+	* Add 'terms' parameter for shortcode and widget
+	* Add GDPR information to readme.txt
+	* deprecate functions (with back compatibility)
+		* km_rpbt_related_posts_by_taxonomy()
+		* km_rpbt_get_default_args()
+		* km_rpbt_related_posts_by_taxonomy_validate_ids()
+		* km_rpbt_related_posts_by_taxonomy_template()
+		* km_rpbt_post_title_link()
+		* km_rpbt_get_related_post_title_link()
+		* km_rpbt_related_posts_by_taxonomy_widget()
+* Bug fixes
+	* (minor) Add missing filter pre_related_posts before cache queries
+	* (minor) Add missing properties to related posts returned by the cache 
+
+= 2.4.1 =
+* Enhancement
+	* Add post classes with filters or as a shortcode or widget argument
+	* Move included current post to the top of the stack by default 
+
 = 2.4.0 =
 * Enhancement
 	* Add post classes with filters or as a shortcode or widget argument

includes/assets/css/styles.css

@@ -0,0 +1,4 @@
+.rpbt-post-date {
+	display: block;
+	font-size: smaller;
+}

includes/assets/partials/widget/columns.php

@@ -0,0 +1,6 @@
+<p class="rpbt_columns">
+	<label for="<?php echo $this->get_field_id( 'columns' ); ?>">
+ 		<?php _e( 'Number of image columns', 'related-posts-by-taxonomy' ); ?>: 
+ 	</label>
+	<input id="<?php echo $this->get_field_id( 'columns' ); ?>" name="<?php echo $this->get_field_name( 'columns' ) ?>" value="<?php esc_attr_e( $i['columns'] ); ?>" size="3" class="tiny-text" step="1" min="0" type="number" />
+</p>

includes/assets/partials/widget/format.php

@@ -0,0 +1,15 @@
+<h4 class="rpbt_display_title"<?php echo $style; ?>>
+	<?php _e( 'Display', 'related-posts-by-taxonomy' ); ?>
+</h4>
+<p class="rpbt_format">
+	<label for="<?php echo $this->get_field_id( 'format' ); ?>">
+		<?php _e( 'Format', 'related-posts-by-taxonomy' ) ?>: 
+	</label>
+	<select name="<?php echo $this->get_field_name( 'format' ); ?>" id="<?php echo $this->get_field_id( 'format' ); ?>" class="widefat">
+		<?php foreach ( $plugin->formats as $name => $label ) : ?>
+			<option value="<?php esc_attr_e( $name ); ?>"<?php selected( $i['format'], $name, true ); ?>>
+				<?php echo $label; ?>
+			</option>
+		<?php endforeach; ?>
+	</select>
+</p>

includes/assets/partials/widget/image-size.php

@@ -0,0 +1,15 @@
+<h4 class="rpbt_widget_image_display_title" <?php echo  $style; ?>>
+	<?php _e( 'Image Display', 'related-posts-by-taxonomy' ); ?>
+</h4>
+<p class="rpbt_image_size">
+	<label for="<?php echo $this->get_field_id( 'image_size' ); ?>">
+		<?php _e( 'Image Size', 'related-posts-by-taxonomy' ); ?>: 
+	</label>
+	<select name="<?php echo $this->get_field_name( 'image_size' ); ?>" id="<?php echo $this->get_field_id( 'image_size' ); ?>" class="widefat">
+		<?php foreach ( $plugin->image_sizes as $name => $label ) : ?>
+			<option value="<?php esc_attr_e( $name ) ?>"<?php selected( $i['image_size'], $name, true ); ?>>
+				<?php echo $label; ?>
+			</option>'
+		<?php endforeach; ?>
+	</select>
+</p>

includes/assets/partials/widget/link-caption.php

@@ -0,0 +1,6 @@
+<p class="rpbt_link_caption">
+	<input class="checkbox" type="checkbox" <?php checked( $i['link_caption'], 1, true ); ?> id="<?php echo $this->get_field_id( 'link_caption' ); ?>" name="<?php echo $this->get_field_name( 'link_caption' ); ?>" />
+ 	<label for="<?php echo $this->get_field_id( 'link_caption' ); ?>">
+ 		<?php _e( 'Link image captions to posts', 'related-posts-by-taxonomy' ); ?>
+	</label>
+</p>

includes/assets/partials/widget/post-id.php

@@ -0,0 +1,6 @@
+<p class="rpbt_post_id">
+	<label for="<?php echo $this->get_field_id( 'post_id' ) ?>">
+		<?php _e( 'Display related posts for post ID (optional)', 'related-posts-by-taxonomy' ); ?>: 
+	</label>
+	<input id="<?php echo $this->get_field_id( 'post_id' ); ?>" name="<?php echo $this->get_field_name( 'post_id' ) ?>" type="text" value="<?php echo $i['post_id']; ?>" size="5" />
+</p>

includes/assets/partials/widget/post-types.php

@@ -0,0 +1,19 @@
+<div class="rpbt_post_types">
+	<h4<?php echo $style; ?>>
+		<?php _e( 'Post Types', 'related-posts-by-taxonomy' ); ?>
+	</h4>
+	<p>
+		<?php foreach ( $plugin->post_types as $name => $label ) : ?>
+			<?php
+				$checked = '';
+				if ( isset( $i['post_types'][ $name ] ) && ( 'on' === $i['post_types'][ $name ] ) ) {
+					$checked = ' checked="checked"';
+				} 
+			?>
+			<input type="checkbox" class="checkbox" id="<?php echo $this->get_field_id( 'post_types' ) . '_' . $name; ?>" name="<?php echo $this->get_field_name( 'post_types' ) . "[$name]"; ?>"<?php echo $checked; ?> />
+			<label for="<?php echo $this->get_field_id( 'post_types' ) . '_' . $name; ?>">
+				<?php echo $label; ?>
+			</label><br />
+		<?php endforeach; ?>
+	</p>
+</div>

includes/assets/partials/widget/posts-per-page.php

@@ -0,0 +1,10 @@
+<p class="rpbt_posts_per_page">
+	<label for="<?php echo $this->get_field_id( 'posts_per_page' ); ?>">
+		<?php _e( 'Number of related posts to show', 'related-posts-by-taxonomy' ); ?>	
+	</label>
+	<input id="<?php echo $this->get_field_id( 'posts_per_page' ); ?>" name="<?php echo $this->get_field_name( 'posts_per_page' ); ?>" value="<?php echo esc_attr_e( $i['posts_per_page'] ); ?>" size="3" class="tiny-text" step="1" min="-1" type="number" />
+	<br/>
+	<span class="description">
+		<?php  _e( 'Use -1 to show all related posts.', 'related-posts-by-taxonomy' ); ?>
+	</span>
+</p>

includes/assets/partials/widget/random.php

@@ -0,0 +1,6 @@
+<p class="rpbt_random">
+	<input class="checkbox" type="checkbox" <?php checked( $i['random'], 1, true ); ?> id="<?php echo $this->get_field_id( 'random' ); ?>" name="<?php echo $this->get_field_name( 'random' ); ?>" />
+	<label for="<?php echo $this->get_field_id( 'random' ); ?>">
+		<?php _e( 'Randomize related posts.', 'related-posts-by-taxonomy' ); ?>
+	</label>
+</p>

includes/assets/partials/widget/show-date.php

@@ -0,0 +1,6 @@
+<p class="rpbt_show_date">
+	<input class="checkbox" type="checkbox"<?php checked( $i['show_date'], 1, true ); ?> id="<?php echo $this->get_field_id( 'show_date' ); ?>" name="<?php echo $this->get_field_name( 'show_date' ); ?>" />
+	<label for="<?php echo $this->get_field_id( 'show_date' ); ?>">
+		<?php _e( 'Display post date', 'related-posts-by-taxonomy' ); ?>
+	</label>
+</p>

includes/assets/partials/widget/singular-template.php

@@ -0,0 +1,9 @@
+<h4 class="rpbt_widget_display_title"<?php echo $style;  ?>>
+	<?php _e( 'Widget Display', 'related-posts-by-taxonomy' ); ?>
+</h4>
+<p class="rpbt_singular_template">
+	<input class="checkbox" type="checkbox" <?php checked( $i['singular_template'], 1, true ); ?> id="<?php echo $this->get_field_id( 'singular_template' ); ?>" name="<?php echo $this->get_field_name( 'singular_template' ); ?>" />
+	<label for="<?php echo $this->get_field_id( 'singular_template' ) ?>">
+		<?php _e( 'Display this widget on single post pages only', 'related-posts-by-taxonomy' ); ?>
+	</label>
+</p>

includes/assets/partials/widget/taxonomies.php

@@ -0,0 +1,18 @@
+<div class="rpbt_taxonomies">
+	<h4<?php echo $style ?>><?php _e( 'Taxonomies', 'related-posts-by-taxonomy' ); ?></h4>
+	<p>
+		<label for="<?php echo $this->get_field_id( 'taxonomies' ); ?>">
+			<?php _e( 'Taxonomy', 'related-posts-by-taxonomy' ); ?>: 
+		</label>
+		<select name="<?php echo $this->get_field_name( 'taxonomies' ); ?>" id="<?php echo $this->get_field_id( 'taxonomies' ) ?>" class="widefat">
+			<option value="<?php esc_attr_e( $plugin->all_tax ) ?>" <?php selected( $i['taxonomies'], $plugin->all_tax, true ) ?>>
+				<?php  _e( 'All Taxonomies', 'related-posts-by-taxonomy' ); ?>
+			</option>
+			<?php foreach ( $plugin->taxonomies as $name => $label ) : ?>
+				<option value="<?php esc_attr_e( $name ) ?>"<?php selected( $i['taxonomies'], $name, true ) ?>>
+					<?php echo $label ?>
+				</option>
+			<?php endforeach; ?>
+		</select>
+	</p>
+</div>

includes/assets/partials/widget/title.php

@@ -0,0 +1,6 @@
+<p class="rpbt_title">
+	<label for="<?php echo $this->get_field_id( 'title' ); ?>">
+		<?php _e( 'Title', 'related-posts-by-taxonomy' ); ?>: 
+	</label>
+	<input id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo  $this->get_field_name( 'title' ); ?>" type="text" value="<?php  esc_attr_e( $i['title'] ); ?>" class="widefat" />
+</p>

includes/class-cache.php

@@ -12,6 +12,9 @@
 }
 
 if ( ! class_exists( 'Related_Posts_By_Taxonomy_Cache' ) ) {
+	/**
+	 * Class to manage the persistent cache feature.
+	 */
 	class Related_Posts_By_Taxonomy_Cache {
 
 		/**
@@ -123,6 +126,8 @@ private function get_cache_settings() {
 		 *
 		 * @since 2.0.1
 		 * @param array $args Array with widget or shortcode args.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return array Array with widget or shortcode args.
 		 */
 		public function add_cache( $args ) {
@@ -135,6 +140,8 @@ public function add_cache( $args ) {
 		 *
 		 * @since 2.0.1
 		 * @param array $args Array with widget or shortcode args.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return array  Array with related post objects .
 		 */
 		public function get_related_posts( $args ) {
@@ -165,6 +172,23 @@ public function get_related_posts( $args ) {
 				$posts = $this->set_cache( $args );
 			}
 
+			$fields = isset( $args['fields'] ) ? (string) $args['fields'] : '';
+
+			$allowed_fields = array(
+				'ids' => 'ID',
+				'names' => 'post_title',
+				'slugs' => 'post_name',
+			);
+
+			if ( $posts ) {
+				if ( in_array( $fields, array_keys( $allowed_fields ) ) ) {
+					/* Get the field used in the query */
+					$posts = wp_list_pluck( $posts, $allowed_fields[ $fields ] );
+				} else {
+					$posts = km_rpbt_add_post_classes( $posts, $args );
+				}
+			}
+
 			return $posts;
 		}
 
@@ -190,6 +214,8 @@ public function update_cache( $args ) {
 		 *
 		 * @since 2.0.1
 		 * @param array $args Array with Widget or shortcode arguments.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return array Array with related post objects that are cached.
 		 */
 		private function set_cache( $args ) {
@@ -252,6 +278,8 @@ private function set_cache( $args ) {
 		 *
 		 * @since 2.0.1
 		 * @param array $args  Array with sanitized widget or shortcode arguments.
+		 *                     See km_rpbt_get_related_posts() for for more
+		 *                     information on accepted arguments.
 		 * @param array $cache Array with cached post ids.
 		 * @return array Array with related post objects.
 		 */
@@ -333,6 +361,8 @@ private function get_cache( $args, $cache ) {
 		 *
 		 * @since 2.1.2
 		 * @param array $args Widget or Shortcode arguments.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return boolean True if post_id and taxonomies are set.
 		 */
 		public function is_valid_cache_args( $args ) {
@@ -349,6 +379,8 @@ public function is_valid_cache_args( $args ) {
 		 *
 		 * @since 2.1
 		 * @param array $args Array with widget or shortcode argument.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return array      Array with sanitized widget or shortcode arguments.
 		 */
 		public function sanitize_cache_args( $args ) {
@@ -371,7 +403,7 @@ public function sanitize_cache_args( $args ) {
 		 *
 		 * @since 2.2
 		 * @param array $args Arguments.
-		 * @return array       Sorted arguments.
+		 * @return array      Sorted arguments.
 		 */
 		public function order_cache_args( $args ) {
 
@@ -392,6 +424,8 @@ public function order_cache_args( $args ) {
 		 *
 		 * @since 2.0.1
 		 * @param array $args Array with widget or shortcode arguments.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return array Array with Related posts ids, empty string, or empty array.
 		 */
 		public function get_post_meta( $args ) {
@@ -404,6 +438,8 @@ public function get_post_meta( $args ) {
 		 *
 		 * @since 2.0.1
 		 * @param array $args Array with widget or shortcode arguments.
+		 *                    See km_rpbt_get_related_posts() for for more
+		 *                    information on accepted arguments.
 		 * @return string Meta key created from sanitized args.
 		 */
 		public function get_post_meta_key( $args ) {
@@ -418,7 +454,9 @@ public function get_post_meta_key( $args ) {
 		 * @param array $results    Related posts. Array with Post objects or post IDs or post titles or post slugs.
 		 * @param int   $post_id    Post id used to get the related posts.
 		 * @param array $taxonomies Taxonomies used to get the related posts.
-		 * @param array $args       Function arguments used to get the related posts.
+		 * @param array $args       Query arguments used to get the related posts.
+		 *                          See km_rpbt_get_related_posts() for for more
+		 *                          information on accepted arguments.
 		 * @return array Array with widget or shortcode args.
 		 */
 		public function current_post( $results, $post_id, $taxonomies, $args ) {

includes/class-debug.php

@@ -11,6 +11,12 @@
 }
 
 if ( ! class_exists( 'Related_Posts_By_Taxonomy_Debug' ) ) {
+	/**
+	 * Class to debug this plugin.
+	 *
+	 * Adds links for debugging shortcodes and widget.
+	 * Displays debug information (to admins) in the footer of a website.
+	 */
 	class Related_Posts_By_Taxonomy_Debug {
 
 		public $debug             = array();

includes/class-defaults.php

@@ -9,6 +9,17 @@
 }
 
 if ( ! class_exists( 'Related_Posts_By_Taxonomy_Defaults' ) ) {
+	/**
+	 * Class to get default data needed by this plugin.
+	 *
+	 * Data needed by this plugin:
+	 *
+	 * - registered taxonomies
+	 * - registered post types
+	 * - default and registered image sizes
+	 * - allowed formats
+	 * - cache instance (if feature is activated)
+	 */
 	class Related_Posts_By_Taxonomy_Defaults {
 
 		/**
@@ -185,12 +196,18 @@ public function get_taxonomies() {
 		}
 
 		/**
-		 * Returns all image sizes.
+		 * Returns default and added image sizes.
+		 *
+		 * Default image sizes
+		 * - thumbnail
+		 * - medium
+		 * - large
+		 * - post-thumbnail
 		 *
 		 * @since 0.2.1
 		 *
 		 * @global array $_wp_additional_image_sizes
-		 * @return array Array with all image sized.
+		 * @return array Array with all image sizes.
 		 */
 		public function get_image_sizes() {
 
@@ -224,7 +241,7 @@ public function get_image_sizes() {
 		}
 
 		/**
-		 * Returns all formats.
+		 * Returns all supported formats.
 		 *
 		 * @since 0.2.1
 		 *