Update examples for embed commands (#75)

* Update docs and examples * Update readme to accommodate new changes in docs * Fix CS error
wp-cli · Apr 4, 2024 · edfa448 · edfa448
1 parent 3987e20
commit edfa448
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -19,7 +19,34 @@ Inspects oEmbed providers, clears embed cache, and more.
 wp embed
 ~~~
 
+**EXAMPLES**
 
+    # Get embed HTML for a given URL.
+    $ wp embed fetch https://www.youtube.com/watch?v=dQw4w9WgXcQ
+    <iframe width="525" height="295" src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed" ...
+
+    # Find cache post ID for a given URL.
+    $ wp embed cache find https://www.youtube.com/watch?v=dQw4w9WgXcQ --width=500
+    123
+
+    # List format,endpoint fields of available providers.
+    $ wp embed provider list
+    +------------------------------+-----------------------------------------+
+    | format                       | endpoint                                |
+    +------------------------------+-----------------------------------------+
+    | #https?://youtu\.be/.*#i     | https://www.youtube.com/oembed          |
+    | #https?://flic\.kr/.*#i      | https://www.flickr.com/services/oembed/ |
+    | #https?://wordpress\.tv/.*#i | https://wordpress.tv/oembed/            |
+
+    # List id,regex,priority fields of available handlers.
+    $ wp embed handler list --fields=priority,id
+    +----------+-------------------+
+    | priority | id                |
+    +----------+-------------------+
+    | 10       | youtube_embed_url |
+    | 9999     | audio             |
+    | 9999     | video             |
+    +----------+-------------------+
 
 
 
@@ -96,7 +123,20 @@ Retrieves oEmbed providers.
 wp embed provider
 ~~~
 
+**EXAMPLES**
 
+    # List format,endpoint fields of available providers.
+    $ wp embed provider list
+    +------------------------------+-----------------------------------------+
+    | format                       | endpoint                                |
+    +------------------------------+-----------------------------------------+
+    | #https?://youtu\.be/.*#i     | https://www.youtube.com/oembed          |
+    | #https?://flic\.kr/.*#i      | https://www.flickr.com/services/oembed/ |
+    | #https?://wordpress\.tv/.*#i | https://wordpress.tv/oembed/            |
+
+    # Get the matching provider for the URL.
+    $ wp embed provider match https://www.youtube.com/watch?v=dQw4w9WgXcQ
+    https://www.youtube.com/oembed
 
 
 
@@ -196,7 +236,16 @@ Retrieves embed handlers.
 wp embed handler
 ~~~
 
+**EXAMPLES**
 
+    # List id,regex,priority fields of available handlers.
+    $ wp embed handler list --fields=priority,id
+    +----------+-------------------+
+    | priority | id                |
+    +----------+-------------------+
+    | 10       | youtube_embed_url |
+    | 9999     | audio             |
+    | 9999     | video             |
 
 
 
@@ -259,7 +308,19 @@ Finds, triggers, and deletes oEmbed caches.
 wp embed cache
 ~~~
 
+**EXAMPLES**
+
+    # Find cache post ID for a given URL.
+    $ wp embed cache find https://www.youtube.com/watch?v=dQw4w9WgXcQ --width=500
+    123
+
+    # Clear cache for a post.
+    $ wp embed cache clear 123
+    Success: Cleared oEmbed cache.
 
+    # Triggers cache for a post.
+    $ wp embed cache trigger 456
+    Success: Caching triggered!
 
 
 

diff --git a/src/Cache_Command.php b/src/Cache_Command.php
@@ -10,6 +10,22 @@
 
 /**
  * Finds, triggers, and deletes oEmbed caches.
+ *
+ * ## EXAMPLES
+ *
+ *     # Find cache post ID for a given URL.
+ *     $ wp embed cache find https://www.youtube.com/watch?v=dQw4w9WgXcQ --width=500
+ *     123
+ *
+ *     # Clear cache for a post.
+ *     $ wp embed cache clear 123
+ *     Success: Cleared oEmbed cache.
+ *
+ *     # Triggers cache for a post.
+ *     $ wp embed cache trigger 456
+ *     Success: Caching triggered!
+ *
+ * @package wp-cli
  */
 class Cache_Command extends WP_CLI_Command {
 

diff --git a/src/Embeds_Namespace.php b/src/Embeds_Namespace.php
@@ -7,6 +7,35 @@
 /**
  * Inspects oEmbed providers, clears embed cache, and more.
  *
+ * ## EXAMPLES
+ *
+ *     # Get embed HTML for a given URL.
+ *     $ wp embed fetch https://www.youtube.com/watch?v=dQw4w9WgXcQ
+ *     <iframe width="525" height="295" src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed" ...
+ *
+ *     # Find cache post ID for a given URL.
+ *     $ wp embed cache find https://www.youtube.com/watch?v=dQw4w9WgXcQ --width=500
+ *     123
+ *
+ *     # List format,endpoint fields of available providers.
+ *     $ wp embed provider list
+ *     +------------------------------+-----------------------------------------+
+ *     | format                       | endpoint                                |
+ *     +------------------------------+-----------------------------------------+
+ *     | #https?://youtu\.be/.*#i     | https://www.youtube.com/oembed          |
+ *     | #https?://flic\.kr/.*#i      | https://www.flickr.com/services/oembed/ |
+ *     | #https?://wordpress\.tv/.*#i | https://wordpress.tv/oembed/            |
+ *
+ *     # List id,regex,priority fields of available handlers.
+ *     $ wp embed handler list --fields=priority,id
+ *     +----------+-------------------+
+ *     | priority | id                |
+ *     +----------+-------------------+
+ *     | 10       | youtube_embed_url |
+ *     | 9999     | audio             |
+ *     | 9999     | video             |
+ *     +----------+-------------------+
+ *
  * @package wp-cli
  */
 class Embeds_Namespace extends CommandNamespace {

diff --git a/src/Fetch_Command.php b/src/Fetch_Command.php
@@ -127,7 +127,7 @@ function ( $args ) use ( $response_size_limit ) {
 			remove_all_filters( 'oembed_dataparse' ); // Save a few cycles.
 			add_filter(
 				'oembed_dataparse',
-				function ( $ret, $data, $url ) {
+				function ( $ret, $data, $url ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter
 					return $data;
 				},
 				PHP_INT_MAX,

diff --git a/src/Handler_Command.php b/src/Handler_Command.php
@@ -8,6 +8,19 @@
 
 /**
  * Retrieves embed handlers.
+ *
+ * ## EXAMPLES
+ *
+ *     # List id,regex,priority fields of available handlers.
+ *     $ wp embed handler list --fields=priority,id
+ *     +----------+-------------------+
+ *     | priority | id                |
+ *     +----------+-------------------+
+ *     | 10       | youtube_embed_url |
+ *     | 9999     | audio             |
+ *     | 9999     | video             |
+ *
+ * @package wp-cli
  */
 class Handler_Command extends WP_CLI_Command {
 	protected $default_fields = array(

diff --git a/src/Provider_Command.php b/src/Provider_Command.php
@@ -9,6 +9,23 @@
 
 /**
  * Retrieves oEmbed providers.
+ *
+ * ## EXAMPLES
+ *
+ *     # List format,endpoint fields of available providers.
+ *     $ wp embed provider list
+ *     +------------------------------+-----------------------------------------+
+ *     | format                       | endpoint                                |
+ *     +------------------------------+-----------------------------------------+
+ *     | #https?://youtu\.be/.*#i     | https://www.youtube.com/oembed          |
+ *     | #https?://flic\.kr/.*#i      | https://www.flickr.com/services/oembed/ |
+ *     | #https?://wordpress\.tv/.*#i | https://wordpress.tv/oembed/            |
+ *
+ *     # Get the matching provider for the URL.
+ *     $ wp embed provider match https://www.youtube.com/watch?v=dQw4w9WgXcQ
+ *     https://www.youtube.com/oembed
+ *
+ * @package wp-cli
  */
 class Provider_Command extends WP_CLI_Command {
 	protected $default_fields = array(