From edfa448396484770a419ac7a17b0ec194ae76654 Mon Sep 17 00:00:00 2001
From: Nilambar Sharma <ernilambar@users.noreply.github.com>
Date: Thu, 4 Apr 2024 17:42:03 +0545
Subject: [PATCH] Update examples for embed commands (#75)

* Update docs and examples

* Update readme to accommodate new changes in docs

* Fix CS error
---
 README.md                | 61 ++++++++++++++++++++++++++++++++++++++++
 src/Cache_Command.php    | 16 +++++++++++
 src/Embeds_Namespace.php | 29 +++++++++++++++++++
 src/Fetch_Command.php    |  2 +-
 src/Handler_Command.php  | 13 +++++++++
 src/Provider_Command.php | 17 +++++++++++
 6 files changed, 137 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index aa6c2ed..64db3c3 100644
--- 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
index 6771bc8..da067a7 100644
--- 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
index cf4621d..39bfa42 100644
--- 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
index b00563c..778643e 100644
--- 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
index d6b1e7c..81f2dda 100644
--- 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
index 77aedd8..295f990 100644
--- 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(