Public-facing functions and tidy up

mattradford · Aug 24, 2021 · abb4a58 · abb4a58
1 parent b4d3fe8
commit abb4a58
Show file tree

Hide file tree

Showing 6 changed files with 202 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -3,33 +3,57 @@
 # Mattrad Primary Categories
 This is a WordPress plugin to assign primary categories to posts and custom post types, for the default _category_ taxonomy only.
 
-You can show primary categories on the front end via a query and a shortcode (`[mr-primary-category]`).
-
 Assigned Primary Categories are shown on the WordPress Dashboard, in the post and custom post type indices, via an admin column.
 
+Show a post's Primary Category with the shortcode `[mr-primary-category]`.
+Get posts with a specified Primary Category using the function `mattrad_get_posts_in_primary_category()`.
+Or for the latest 10 posts with a specified Primary Category use the speedy function `mattrad_get_latest_posts_in_primary_category()`.
+
+## Testing
+
 This plugin has been tested with WordPress [Theme Test Data](https://github.com/WPTT/theme-test-data) and the following themes:
 
 * Twenty Nineteen
-* TwentyTwenty
-* TwentyTwentyOne
+* Twenty Twenty
+* Twenty Twenty-One
 
 Both Classic Editor and Block Editor are supported.
 
+This plugin has *not* been tested with WordPress Multisite.
+
+## Pre-requisites
+
+* WordPress 5.8
+* PHP 7.3
+
+The plugin is likely to work on earlier versions of WordPress and PHP, but these have not been tested.
+
 ## Installation
 
-* Download the [latest release](https://github.com/mattradford/mattrad-primary-categories/releases)
-* Upload the zip file via Plugins -> Add new
+* Download the [latest release](https://github.com/mattradford/mattrad-primary-category/releases/)
+* Upload the zip file via _Plugins_ -> _Add new_
 * Activate
 * Assign Primary Categories via the post edit screen
 
+Or you may install via [Composer](https://getcomposer.org/).
+
 ## Uninstallation
 
 * When the plugin is deleted, it will remove any Primary Category metadata that has been set.
 
-## Pre-requisites
+## Functions
 
-* WordPress 5.8
-* PHP 7.3
+`mattrad_get_posts_in_primary_category()` accepts two parameters:
+
+* `$term`
+  * This should be a valid Primary Category term name.
+* `$args`
+  * This allows the use of [WP_Query parameters](https://developer.wordpress.org/reference/classes/wp_query/#parameters).
+
+`mattrad_get_latest_posts_in_primary_category()` accepts two parameters:
+
+* `$term`
+  * This should be a valid Primary Category term name.
 
 ## Shortcode options
 
@@ -39,13 +63,16 @@ Both Classic Editor and Block Editor are supported.
   * This defaults to `true` and outputs the post's Primary Category as a link to the Category Archive.
   * Use `link="false"` if you just want the name of the Primary Category to show.
 * `text`
- * This defaults to `Category: ` and is prepended to the post's Primary Category.
- * Use `text=""` to remove or `text="Your text here "`.
+  * This defaults to `Category: ` and is prepended to the post's Primary Category.
+  * Use `text=""` to remove or `text="Your text here "` to set custom text.
 
 ## To-Do
 
 * Internationalisation
 * Support for Tags (_post_tags_)
+* Options page to allow admins to choose post types that primary categories can be applied to
 * REST API route
 * Activation and Deactivation functions
 * Support for custom taxonomies
+* Possible: Re-factor to store Primary Categories by ID rather than name
+* Possible: Primary Category Archives (could use _pre_get_post_ to alter existing archives)
diff --git a/admin/class-mattrad-primary-category-set.php b/admin/class-mattrad-primary-category-set.php
@@ -181,6 +181,5 @@ public function add_admin_columns() {
             }, 10, 2);
         }
     }
-
 }
 new Mattrad_Primary_Category_Set();
diff --git a/includes/class-mattrad-primary-category.php b/includes/class-mattrad-primary-category.php
@@ -86,13 +86,11 @@ public function require_files() {
         require_once( MPC_PLUGIN_DIR . '/includes/helpers.php' );
 
         // Public facing functions.
-        require_once( MPC_PLUGIN_DIR . '/public/class-mattrad-primary-category-query.php' );
         require_once( MPC_PLUGIN_DIR . '/public/mattrad-primary-category-functions.php' );
 
         // WP Admin only functions.
 		if ( is_admin() ) {
             require_once( MPC_PLUGIN_DIR . '/admin/class-mattrad-primary-category-set.php' );
 		}
     }
-
 }
diff --git a/public/class-mattrad-primary-category-query.php b/public/class-mattrad-primary-category-query.php
diff --git a/public/mattrad-primary-category-functions.php b/public/mattrad-primary-category-functions.php
@@ -12,8 +12,159 @@
  * @since    1.0.0
  */
 
+ /**
+ * Check term is valid.
+ *
+ * @param string    $term Category term
+ * @return object   $primary_category_term
+ */
+function mattrad_get_valid_primary_category( $term ) {
+    // Check a term has been supplied.
+    if ( null === $term ) {
+        return new WP_Error( 'no_term_specified', __( 'No primary category specified.' ) );
+    }
+
+    // Get the term object
+    $term = esc_html( $term );
+    $primary_category_term = get_term_by( 'name', $term , 'category' );
+
+    // Check a term is valid.
+    if ( ! $primary_category_term || is_wp_error( $primary_category_term ) ) {
+        return new WP_Error( 'invalid_term_specified', __( 'Invalid primary category specified.' ) );
+    }
+
+    return $primary_category_term;
+}
+
+/**
+ * Get all public post types.
+ *
+ * @return array   $post_types
+ */
+function mattrad_get_public_post_types() {
+    // Get all public post types as default.
+    $post_type_args = [
+        'public' => true,
+        '_builtin' => false,
+    ];
+    $post_types = get_post_types( $post_type_args );
+    $post_types = array_values( $post_types );
+    // Include "post" post type.
+    $post_types[] = 'post';
+
+    return $post_types;
+}
+
+/**
+ * Get all posts with a Primary Category, by term.
+ *
+ * @param string    $term Category term
+ * @param array     $args WP_Query arguments
+ * @return object
+ */
+function mattrad_get_posts_in_primary_category( $term = 'null', $args = [] ) {
+    $primary_category_term = mattrad_get_valid_primary_category( $term );
+    $post_types = mattrad_get_public_post_types();
+
+    // Monitor query run time, if that's your thing.
+    // $start_time = microtime(true);
+
+    $default_args = [
+        'post_type'        => $post_types,
+        'post_status'      => 'publish',
+        'cat'              => $primary_category_term->term_id,
+        'posts_per_page'   => 10,
+        'meta_query' => [
+            [
+                'key'     => 'mattrad_primary_category',
+                'value'   => $primary_category_term->name,
+                'compare' => '=',
+            ],
+        ],
+    ];
+
+    // Get user-supplied query arguments.
+    $query_args = wp_parse_args( $args, $default_args );
+
+    // Build a new query.
+    $primary_posts = new WP_Query( $query_args );
+
+    // Query monitoring end.
+    // $end_time = microtime(true);
+    // $execution_time = ($end_time - $start_time);
+    // dd('mattrad_get_posts_in_primary_category() ran in ' . round($execution_time, 3) . ' sec');
+
+    return $primary_posts;
+}
+
+/**
+ * Get latest 10 posts with a Primary Category, by term.
+ *
+ * Parameters are more tightly controlled for this function.
+ * So let's apply some caching :)
+ *
+ * @param string    $term Category term
+ * @return object
+ */
+function mattrad_get_latest_posts_in_primary_category( $term = 'null' ) {
+    $primary_category_term = mattrad_get_valid_primary_category( $term );
+    $post_types = mattrad_get_public_post_types();
+
+    $cache_key = 'mattrad_primary_posts_in_'. strtolower($primary_category_term->name);
+    $latest_primary_posts = wp_cache_get( $cache_key );
+
+    if ( false === $latest_primary_posts ) {
+        $default_args = [
+            'post_type'        => $post_types,
+            'post_status'      => 'publish',
+            'cat'              => $primary_category_term->term_id,
+            'posts_per_page'   => 10,
+            'no_found_rows'     => true,
+            'meta_query' => [
+                [
+                    'key'     => 'mattrad_primary_category',
+                    'value'   => $primary_category_term->name,
+                    'compare' => '=',
+                ],
+            ],
+        ];
+
+        // Build a new query.
+        $latest_primary_posts = new WP_Query( $default_args );
+        wp_cache_set( $cache_key, $latest_primary_posts );
+    }
+
+    return $latest_primary_posts;
+}
+
+ /**
+ * Get Primary Category for the post.
+ *
+ * Same premise as get_the_category(), except for a single term.
+ * This function may be used outside The Loop by passing a post ID as the parameter.
+ *
+ * @param int           $post_id
+ * @return object|null  $primary_category_term
+ * @link https://developer.wordpress.org/reference/functions/get_the_category/
+ */
+function mattrad_get_the_primary_category( $post_id = null ) {
+    if ( null !== $post_id ) {
+        $post_id = (int) $post_id;
+    } else {
+        $post_id = $post->ID;
+    }
+
+    // Get the primary category.
+    $primary_category_assigned = get_post_meta( $post_id, 'mattrad_primary_category', true );
+    $primary_category_term = mattrad_get_valid_primary_category( $primary_category_assigned  );
+
+    return $primary_category_term;
+}
+
  /**
  * Register all shortcodes.
+ *
+ * @return void
  */
 function mattrad_shortcodes_init() {
     add_shortcode( 'mr_primary_category', 'mr_primary_category' );
@@ -25,33 +176,30 @@ function mattrad_shortcodes_init() {
  *
  * Displays the Primary Category, if assigned.
  *
- * @return string|null Primary Category name|null.
+ * @param string        $output
+ * @param object|null   $primary_category_term
+ * @param string        $primary_category_text
+ * @return string|null  Primary Category name|null.
  */
 function mr_primary_category( $atts = [] ) {
     $output = '';
     global $post;
 
-    // Default parameter
+    // Default parameters
     extract( shortcode_atts( [
         'link' => 'true',
         'text' => __( 'Category:&nbsp;' ),
     ], $atts ) );
 
-    // Get the existing primary category.
-    $primary_category_assigned = get_post_meta( $post->ID, 'mattrad_primary_category', true );
-
-    // Get term object and build link.
-    if ( ! is_wp_error( $primary_category_assigned ) && ! empty( $primary_category_assigned ) ) {
-        $primary_category_assigned = esc_html( $primary_category_assigned );
-        $primary_category_term = get_term_by( 'name', $primary_category_assigned, 'category' );
-        if ( 'false' === $link ) {
-            $primary_category_text = '<span>' . __( $primary_category_term->name ) . '</span>';
-        } else {
-            $primary_category_text = '<a href="' . get_term_link( $primary_category_term->slug, 'category' ) . '">' . __( $primary_category_term->name ) . '</a>';
-        }
+    $primary_category_term = mattrad_get_the_primary_category($post->ID);
+
+    if ( 'false' === $link ) {
+        $primary_category_text = '<span>' . __( $primary_category_term->name ) . '</span>';
+    } else {
+        $primary_category_text = '<a href="' . get_term_link( $primary_category_term->slug, 'category' ) . '">' . __( $primary_category_term->name ) . '</a>';
     }
 
-    if ( null != $primary_category_assigned && ! empty( $primary_category_text ) ) {
+    if ( null !== $primary_category_term && ! empty( $primary_category_text ) ) {
         $output = '<span class="mr-primary-category-assigned">';
         $output .= esc_html( $text );
         $output .= $primary_category_text;

diff --git a/uninstall.php b/uninstall.php
@@ -2,7 +2,7 @@
 /**
  * Mattrad Primary Category Uninstall.
  *
- * These functions will remove database entries for Mattrad Primary Category.
+ * This file will remove database entries for Mattrad Primary Category.
  *
  * @category Plugin
  * @package  mattrad-primary-category