Merge pull request #839 from alleyinteractive/feature/v2.1.1

Release v2.1.1

.deployignore

@@ -18,7 +18,6 @@ npm-debug.log
 .eslintrc.json
 .github
 .travis.yml
-assets/images
 assets/js/pluginsidebar
 assets/js/util
 bin

.travis.yml

@@ -16,7 +16,7 @@ language: php
 branches:
   only:
     - develop
-    - feature/v2.1.0
+    - feature/v2.1.1
 
 cache:
   directories:
@@ -32,8 +32,10 @@ git:
 matrix:
   fast_finish: true
   include:
-    - php: 7.3
+    - php: 7.4
       env: WP_VERSION=latest PHP_LINT=1 WP_PHPCS=1 WP_JS=1
+    - php: 7.3
+      env: WP_VERSION=latest PHP_LINT=1
     - php: 7.2
       env: WP_VERSION=latest PHP_LINT=1
     - php: 7.1
@@ -42,8 +44,6 @@ matrix:
       env: WP_VERSION=latest PHP_LINT=1
     - php: 5.6
       env: WP_VERSION=latest PHP_LINT=1
-    - php: 7.3
-      env: WP_VERSION=nightly
 
 # Use this to prepare your build for testing.
 # e.g. copy database configurations, environment variables, etc.

admin/apple-actions/index/class-delete.php

@@ -72,6 +72,12 @@ private function delete() {
 		}
 
 		try {
+			/**
+			 * Actions to be taken before an article is deleted via the API.
+			 *
+			 * @param string $remote_id The API ID of the article from Apple's servers.
+			 * @param int    $post_id   The post ID from WordPress.
+			 */
 			do_action( 'apple_news_before_delete', $remote_id, $this->id );
 			$this->get_api()->delete_article( $remote_id );
 
@@ -86,6 +92,12 @@ private function delete() {
 			// Clear the cache for post status.
 			delete_transient( 'apple_news_post_state_' . $this->id );
 
+			/**
+			 * Actions to be taken after an article is deleted via the API.
+			 *
+			 * @param string $remote_id The API ID of the article from Apple's servers.
+			 * @param int    $post_id   The post ID from WordPress.
+			 */
 			do_action( 'apple_news_after_delete', $remote_id, $this->id );
 		} catch ( \Exception $e ) {
 			return $e->getMessage();

admin/apple-actions/index/class-export.php

@@ -93,6 +93,11 @@ public function fetch_exporter() {
 
 		global $post;
 
+		/**
+		 * Actions to be fired before the Exporter class is created and returned.
+		 *
+		 * @param int $post_id The ID of the post being exported.
+		 */
 		do_action( 'apple_news_do_fetch_exporter', $this->id );
 
 		/**
@@ -159,22 +164,70 @@ public function fetch_exporter() {
 			}
 		}
 
-		// Filter each of our items before passing into the exporter class.
-		$title     = apply_filters( 'apple_news_exporter_title', $post->post_title, $post->ID );
-		$excerpt   = apply_filters( 'apple_news_exporter_excerpt', $excerpt, $post->ID );
+		/**
+		 * Filters the title of an article before it is sent to Apple News.
+		 *
+		 * @param string $title   The title of the post.
+		 * @param int    $post_id The ID of the post.
+		 */
+		$title = apply_filters( 'apple_news_exporter_title', $post->post_title, $post->ID );
+
+		/**
+		 * Filters the excerpt of an article before it is sent to Apple News.
+		 *
+		 * The excerpt is used for the Intro component, if it is active.
+		 *
+		 * @param string $excerpt The excerpt of the post.
+		 * @param int    $post_id The ID of the post.
+		 */
+		$excerpt = apply_filters( 'apple_news_exporter_excerpt', $excerpt, $post->ID );
+
+		/**
+		 * Filters the cover image URL of an article before it is sent to Apple News.
+		 *
+		 * The cover image URL is used for the Cover component, if it is active.
+		 *
+		 * @param string|null $url     The cover image URL for the post.
+		 * @param int         $post_id The ID of the post.
+		 */
 		$cover_url = apply_filters( 'apple_news_exporter_post_thumb', ! empty( $post_thumb['url'] ) ? $post_thumb['url'] : null, $post->ID );
-		$byline    = apply_filters( 'apple_news_exporter_byline', $byline, $post->ID );
-		$content   = apply_filters( 'apple_news_exporter_content', $content, $post->ID );
+
+		/**
+		 * Filters the byline of an article before it is sent to Apple News.
+		 *
+		 * The byline is used for the Byline component, if it is active.
+		 *
+		 * @param string $byline  The byline for the post.
+		 * @param int    $post_id The ID of the post.
+		 */
+		$byline = apply_filters( 'apple_news_exporter_byline', $byline, $post->ID );
+
+		/**
+		 * Filters the HTML of a post after `the_content` filter is called, but
+		 * before the HTML is parsed into Apple News Format.
+		 *
+		 * This filter could be useful to remove content known to be incompatible
+		 * with Apple News, or to add content stored in other areas of the
+		 * database, such as postmeta or custom database tables.
+		 *
+		 * @param string $content The HTML content of the post, after the_content filter has been run.
+		 * @param int    $post_id The ID of the post.
+		 */
+		$content = apply_filters( 'apple_news_exporter_content', $content, $post->ID );
 
 		// Re-apply the cover URL after filtering.
 		if ( ! empty( $cover_url ) ) {
 			$cover_caption = ! empty( $post_thumb['caption'] ) ? $post_thumb['caption'] : '';
 
 			/**
-			 * Filters the cover caption.
+			 * Filters the cover image caption of an article before it is sent to Apple News.
+			 *
+			 * The cover image caption is used for the Cover component, if it is
+			 * active, and if support for cover image captions is turned on in theme
+			 * settings.
 			 *
 			 * @param string $caption The caption to use for the cover image.
-			 * @param int    $post_id The post ID.
+			 * @param int    $post_id The ID of the post.
 			 *
 			 * @since 2.1.0
 			 */
@@ -386,16 +439,34 @@ private function get_brightcove_stillurl( $account_id, $video_id ) {
 	 * @return string
 	 */
 	private function get_content( $post ) {
+		/**
+		 * Filters the HTML of a post before `the_content` filter is called, and
+		 * before the HTML is parsed into Apple News Format.
+		 *
+		 * This filter could be useful to remove content known to be incompatible
+		 * with Apple News, or to add content stored in other areas of the
+		 * database which should be run through `the_content` filter, such as
+		 * shortcodes stored in postmeta or custom database tables.
+		 *
+		 * @param string $content The post_content for the post, before the_content filter has been run.
+		 * @param int    $post_id The ID of the post.
+		 */
+		$content = apply_filters( 'apple_news_exporter_content_pre', $post->post_content, $post->ID );
+
+		// Replace Brightcove shortcodes and Gutenberg blocks with video tags.
+		$content = $this->format_brightcove( $content );
+
 		/**
 		 * The post_content is not raw HTML, as WordPress editor cleans up
 		 * paragraphs and new lines, so we need to transform the content to
 		 * HTML. We use 'the_content' filter for that.
 		 */
-		$content = apply_filters( 'apple_news_exporter_content_pre', $post->post_content, $post->ID );
-		$content = $this->format_brightcove( $content );
 		$content = apply_filters( 'the_content', $content ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound
+
+		// Clean up the HTML a little.
 		$content = $this->remove_tags( $content );
 		$content = $this->remove_entities( $content );
+
 		return $content;
 	}
 
@@ -445,6 +516,15 @@ private function fetch_content_settings() {
 				$settings->set( $name, $value );
 			}
 		}
+
+		/**
+		 * Filters the Exporter_Content_Settings object for this article.
+		 *
+		 * Before this filter is called, the Exporter_Content_Settings object is
+		 * initialized and merged with settings stored in postmeta for this post.
+		 *
+		 * @param Apple_Exporter\Exporter_Content_Settings $settings The content settings for this article.
+		 */
 		return apply_filters( 'apple_news_content_settings', $settings );
 	}
 

admin/apple-actions/index/class-push.php

@@ -147,7 +147,7 @@ private function is_post_in_sync( $json, $meta = [], $bundles = [] ) {
 		// Ensure the post (still) exists. Async operations might result in this function being run against a non-existent post.
 		$post = get_post( $this->id );
 		if ( ! $post ) {
-			throw new \Apple_Actions\Action_Exception( __( 'Could not find post with id ', 'apple-news' ) . $this->id );
+			throw new \Apple_Actions\Action_Exception( __( 'Apple News Error: Could not find post with id ', 'apple-news' ) . $this->id );
 		}
 
 		// Compare checksums to determine whether the article is in sync or not.
@@ -160,6 +160,11 @@ private function is_post_in_sync( $json, $meta = [], $bundles = [] ) {
 		/**
 		 * Allows for custom logic to determine if a post is in sync or not.
 		 *
+		 * By default, the plugin simply compares the last modified time to the
+		 * last time it was pushed to Apple News. If you want to apply custom
+		 * logic, you can do that by modifying `$in_sync`. The most common use case
+		 * is to not update posts based on custom criteria.
+		 *
 		 * @since 2.0.2 Added the $post_id, $json, $meta, and $bundles parameters.
 		 *
 		 * @param bool   $in_sync Whether the current post is in sync or not.
@@ -188,7 +193,7 @@ private function get() {
 		// Get the article from the API.
 		$result = $this->get_api()->get_article( $apple_id );
 		if ( empty( $result->data->revision ) ) {
-			throw new \Apple_Actions\Action_Exception( __( 'The API returned invalid data for this article since the revision is empty.', 'apple-news' ) );
+			throw new \Apple_Actions\Action_Exception( __( 'The Apple News API returned invalid data for this article since the revision is empty.', 'apple-news' ) );
 		}
 
 		// Update the revision.
@@ -208,9 +213,15 @@ private function push( $user_id = null ) {
 		}
 
 		/**
-		 * Should the post be skipped and not pushed to apple news.
+		 * Filters whether the post should be skipped and not pushed to Apple News.
+		 *
+		 * Allows you to stop publication of a post to Apple News based on your own
+		 * custom logic. A common use case is to not publish posts with a certain
+		 * category or tag. By default this is always `false` as all posts are
+		 * published once they reach this step.
 		 *
-		 * Default is false, but filterable.
+		 * @param bool $skip    Whether the post should be skipped. Defaults to `false`.
+		 * @param int  $post_id The ID of the post.
 		 */
 		if ( apply_filters( 'apple_news_skip_push', false, $this->id ) ) {
 			throw new \Apple_Actions\Action_Exception(
@@ -251,6 +262,11 @@ private function push( $user_id = null ) {
 		$remote_id = get_post_meta( $this->id, 'apple_news_api_id', true );
 		$result    = null;
 
+		/**
+		 * Actions to be taken before the article is pushed to Apple News.
+		 *
+		 * @param int $post_id The ID of the post.
+		 */
 		do_action( 'apple_news_before_push', $this->id );
 
 		// Populate optional metadata.
@@ -291,7 +307,7 @@ private function push( $user_id = null ) {
 			throw new \Apple_Actions\Action_Exception(
 				sprintf(
 					// Translators: Placeholder is a post ID.
-					__( 'Skipped push of article %d because it is already in sync.', 'apple-news' ),
+					__( 'Skipped push of article %d to Apple News because it is already in sync.', 'apple-news' ),
 					$this->id
 				)
 			);
@@ -331,6 +347,12 @@ private function push( $user_id = null ) {
 			// Update the checksum for the article JSON version.
 			update_post_meta( $this->id, 'apple_news_article_checksum', $this->generate_checksum( $json, $meta, $bundles ) );
 
+			/**
+			 * Actions to be taken after an article was pushed to Apple News.
+			 *
+			 * @param int    $post_id The ID of the post.
+			 * @param object $result  The JSON returned by the Apple News API.
+			 */
 			do_action( 'apple_news_after_push', $this->id, $result );
 		} catch ( \Apple_Push_API\Request\Request_Exception $e ) {
 
@@ -343,9 +365,9 @@ private function push( $user_id = null ) {
 			$this->clean_workspace();
 
 			if ( preg_match( '#WRONG_REVISION#', $e->getMessage() ) ) {
-				throw new \Apple_Actions\Action_Exception( __( 'It seems like the article was updated by another call. If the problem persists, try removing and pushing again.', 'apple-news' ) );
+				throw new \Apple_Actions\Action_Exception( __( 'Apple News Error: It seems like the article was updated by another call. If the problem persists, try removing and pushing again.', 'apple-news' ) );
 			} else {
-				throw new \Apple_Actions\Action_Exception( __( 'There has been an error with the API: ', 'apple-news' ) . $e->getMessage() );
+				throw new \Apple_Actions\Action_Exception( __( 'There has been an error with the Apple News API: ', 'apple-news' ) . $e->getMessage() );
 			}
 		}
 
@@ -425,13 +447,13 @@ private function process_errors( $errors ) {
 			if ( 'warn' === $json_alerts ) {
 				$alert_message .= sprintf(
 					// translators: token is a list of errors.
-					__( 'The following JSON errors were detected: %s', 'apple-news' ),
+					__( 'The following JSON errors were detected when publishing to Apple News: %s', 'apple-news' ),
 					$json_errors
 				);
 			} elseif ( 'fail' === $json_alerts ) {
 				$alert_message .= sprintf(
 					// translators: token is a list of errors.
-					__( 'The following JSON errors were detected and prevented publishing: %s', 'apple-news' ),
+					__( 'The following JSON errors were detected and prevented publishing to Apple News: %s', 'apple-news' ),
 					$json_errors
 				);
 			}

admin/class-admin-apple-async.php

@@ -57,12 +57,15 @@ public function __construct( $settings ) {
 	 */
 	public function async_push( $post_id, $user_id ) {
 		/**
+		 * Optional actions to be taken before an async push starts.
+		 *
 		 * This hook could be used for an ini_set to increase max execution time
-		 * for asynchronous publishing to handle large push requests.
-		 * Since some hosts wouldn't support it, the code isn't added directly here.
+		 * for asynchronous publishing to handle large push requests. Since some
+		 * hosts wouldn't support it, the code isn't added directly here.
 		 *
-		 * On WordPress VIP this isn't necessary since the plugin
-		 * will automatically use the jobs system which can handle requests up to 12 hours.
+		 * On WordPress VIP this isn't necessary since the plugin will
+		 * automatically use the jobs system which can handle requests up to 12
+		 * hours.
 		 */
 		do_action( 'apple_news_before_async_push' );
 
@@ -95,6 +98,12 @@ public function async_push( $post_id, $user_id ) {
 			Admin_Apple_Notice::error( $e->getMessage(), $user_id );
 		}
 
+		/**
+		 * Optional actions to be taken after an async push completes.
+		 *
+		 * This hook could be used to undo changes that were made in the
+		 * apple_news_before_async_push action.
+		 */
 		do_action( 'apple_news_after_async_push' );
 	}
 

admin/class-admin-apple-bulk-export-page.php

@@ -55,6 +55,11 @@ public function register_page() {
 			null,                                // Parent, if null, it won't appear in any menu.
 			__( 'Bulk Export', 'apple-news' ),   // Page title.
 			__( 'Bulk Export', 'apple-news' ),   // Menu title.
+			/**
+			 * Filters the capability required to be able to access the Bulk Export page.
+			 *
+			 * @param string $capability The capability required to be able to perform bulk exports. Defaults to 'manage_options'.
+			 */
 			apply_filters( 'apple_news_bulk_export_capability', 'manage_options' ), // Capability.
 			$this->plugin_slug . '_bulk_export', // Menu Slug.
 			array( $this, 'build_page' )         // Function.
@@ -128,7 +133,10 @@ public function ajax_push_post() {
 		}
 
 		// Check capabilities.
-		if ( ! current_user_can( apply_filters( 'apple_news_publish_capability', self::get_capability_for_post_type( 'publish_posts', $post->post_type ) ) ) ) {
+		if ( ! current_user_can(
+			/** This filter is documented in admin/class-admin-apple-post-sync.php */
+			apply_filters( 'apple_news_publish_capability', self::get_capability_for_post_type( 'publish_posts', $post->post_type ) )
+		) ) {
 			echo wp_json_encode(
 				array(
 					'success' => false,