Comunicación con la API del complemento de WordPress.org

Durante las últimas semanas me he estado preguntando cómo es posible extraer datos sobre mis complementos alojados en WordPress.org y mostrarlos en mi sitio web. Lo primero que me vino a la mente fue "Web Scrapping" pero, francamente, esto es mucho trabajo, se siente como retroceder en el tiempo y no es algo que un buen ciudadano de la web deba hacer. En algunos casos, podría ser ilegal.

Luego me encontré con un complemento llamado "I Make Plugins", desarrollado por Mark Jaquith, que solo quería que yo buscara datos del archivo readme.txt de un complemento. Funciona muy bien, pero dado que WordPress nos permite buscar complementos directamente desde el backend y también ver nuestros complementos favoritos, sabía que había una manera mejor (o la manera de WordPress) y una búsqueda más profunda me llevó a la API de WordPress.org. No hay documentación detallada en esta página, pero lo suficiente para comenzar sabiendo que hay una API para hacer esto de manera más eficiente.

Complementos de la API de WordPress.org

La URL donde se realizan todas las llamadas relacionadas con la búsqueda y/o actualización de complementos es http://api.wordpress.org/plugins/info/1.0/. Para tener una idea rápida de cómo funciona esto, abre este enlace en un navegador y agrega el slug de tu plugin al final, por ejemplo, http://api.wordpress.org/plugins/info/1.0/custom-favicon/ y mira lo que se retorna.

Esta solicitud GET basada en el navegador mostró toda la información del complemento llamado "Custom Favicon (Favicon personalizado)" en el siguiente formato. Al reemplazar la última ruta de la URL con el slug de tu complemento, podrás ver los detalles específicos de tu complemento.

1

O:8:"stdClass":20:{s:4:"name";s:14:"Custom Favicon";s:4:"slug";s:14:"custom-favicon";s:7:"version";s:3:"1.0";s:6:"author";s:80:"<a href="http://www.dreamsonline.net/wordpress-themes/">Dreams Online Themes</a>";s:14:"author_profile";s:38:"http://profiles.wordpress.org/hchouhan";s:12:"contributors";a:3:{s:8:"hchouhan";s:38:"http://profiles.wordpress.org/hchouhan";s:12:"dreamsonline";s:42:"http://profiles.wordpress.org/dreamsonline";s:11:"dreamsmedia";s:41:"http://profiles.wordpress.org/dreamsmedia";}s:8:"requires";s:3:"3.5";s:6:"tested";s:5:"3.5.2";s:13:"compatibility";a:2:{s:5:"3.5.1";a:1:{s:3:"1.0";a:3:{i:0;i:100;i:1;i:5;i:2;i:5;}}s:3:"3.6";a:1:{s:3:"1.0";a:3:{i:0;i:100;i:1;i:1;i:2;i:1;}}}s:6:"rating";d:100;s:11:"num_ratings";i:3;s:10:"downloaded";i:1995;s:12:"last_updated";s:10:"2013-05-27";s:5:"added";s:10:"2013-05-27";s:8:"homepage";s:61:"http://www.dreamsonline.net/wordpress-plugins/custom-favicon/";s:8:"sections";a:4:{s:11:"description";s:594:"<p>Now easily upload a favicon and apple touch icon for your WordPress website and dashboard.</p></pre>

2

<p>Please report any bugs you find via <a href="http://www.dreamsonline.net/wordpress-plugins/custom-favicon/" rel="nofollow">http://www.dreamsonline.net/wordpress-plugins/custom-favicon/</a></p>

3

4

<h4>My Links</h4>

5

6

<ul>

7

8

<li>Twitter @<a href="https://twitter.com/dreams_media">harishchouhan</a></li>

9

10

<li>Google+ <a href="https://plus.google.com/u/0/103138475844539274387/">Harish Chouhan</a></li>

11

12

</ul>

No es muy presentable, pero bueno, al menos este es un buen comienzo para probar si la API entrega información de complementos rápidamente, que luego podemos mostrar de la manera que queramos.

Hasta este punto, la mayor parte de lo que yo estaba haciendo se basaba en ensayos aleatorios. El único recurso que pude encontrar fue http://dd32.id.au/projects/wordpressorg-plugin-information-api-docs/ que intenta explicar las diversas opciones y argumentos que se pueden usar al comunicarse con esta API.

¿Entonces, cómo funciona esto?

Para comunicarse con http://api.wordpress.org/plugins/info/1.0/ y recuperar información, debes realizar una solicitud $POST con 2 cosas:

1. Enviar una petición POST con una acción: por ejemplo, $ _POST['action']
2. Enviar una petición POST con un contenido más específico: por ejemplo $ _POST ['body'], que sería un objeto serializado

Los datos devueltos de la API son un Objeto en todos los casos (excepto cuando se visita el enlace de la API desde un navegador). Incluso en caso de error, los datos devueltos siguen siendo un objeto pero con una sola propiedad, una cadena de error.

Mi primer intento de recuperar la información del complemento fue algo como el siguiente ejemplo:

Ejemplo de obtención de información del complemento mediante la API HTTP wp_remote_post

1

<?php

2

3

	$args = (object) array( 'slug' => 'custom-favicon' );

4

5

	$request = array( 'action' => 'plugin_information', 'timeout' => 15, 'request' => serialize( $args) );

6

7

	$url = 'http://api.wordpress.org/plugins/info/1.0/';

8

9

	$response = wp_remote_post( $url, array( 'body' => $request ) );

10

11

	$plugin_info = unserialize( $response['body'] );

12

13

	echo '<pre>' . print_r( $plugin_info, true ) . '</pre>';

14

15

?>

Explicaremos el código más adelante, pero por ahora el código de ejemplo anterior devolverá información sobre nuestro complemento en el formato que se muestra a continuación, en caso de que todo funcione según lo previsto:

1

stdClass Object

2

(

3

    [name] => Custom Favicon

4

    [slug] => custom-favicon

5

    [version] => 1.0

6

    [author] => Dreams Online Themes

7

    [author_profile] => http://profiles.wordpress.org/hchouhan

8

    [contributors] => Array

9

        (

10

            [hchouhan] => http://profiles.wordpress.org/hchouhan

11

            [dreamsonline] => http://profiles.wordpress.org/dreamsonline

12

            [dreamsmedia] => http://profiles.wordpress.org/dreamsmedia

13

        )

14

15

    [requires] => 3.5

16

    [tested] => 3.5.2

17

    [compatibility] => Array

18

        (

19

            [3.6] => Array

20

                (

21

                    [1.0] => Array

22

                        (

23

                            [0] => 100

24

                            [1] => 1

25

                            [2] => 1

26

                        )

27

28

                )

29

30

        )

31

32

    [rating] => 100

33

    [num_ratings] => 3

34

    [downloaded] => 2008

35

    [last_updated] => 2013-05-27

36

    [added] => 2013-05-27

37

    [homepage] => http://www.dreamsonline.net/wordpress-plugins/custom-favicon/

38

    [sections] => Array

39

        (

40

            [description] =>

41

Now easily upload a favicon and apple touch icon for your WordPress website and dashboard.

42

43

44

45

Please report any bugs you find via http://www.dreamsonline.net/wordpress-plugins/custom-favicon/

46

47

48

49

My Links

50

51

52

53

54

Twitter @harishchouhan

55

56

Google+ Harish Chouhan

57

58

59

60

If you love the plugin, please consider rating it and clicking on "it works" button.

61

62

63

            [installation] =>

64

65

Upload the directory /custom-favicon/ to the /wp-content/plugins/ directory

66

67

Activate the plugin through the 'Plugins' menu in WordPress

68

69

Click on "Custom Favicon" sub menu under the Settings menu and upload your favicon

70

71

72

            [changelog] =>

73

= 1.0.0

74

* This is the first version

75

76

77

            [faq] =>

78

Take a look at the official "Custom Favicon" FAQ.

79

80

81

82

You can also visit the support center and start a discussion if needed.

83

84

85

        )

86

87

    [download_link] => http://downloads.wordpress.org/plugin/custom-favicon.zip

88

    [tags] => Array

89

        (

90

            [admin] => admin

91

            [apple-touch] => apple touch

92

            [apple-touch-icon] => apple touch icon

93

            [blog] => blog

94

            [favicon] => favicon

95

            [icon] => icon

96

            [iphone] => iphone

97

            [theme] => theme

98

            [upload] => upload

99

            [wordpress] => wordpress

100

        )

101

102

    [donate_link] => http://www.dreamsonline.net

103

)

Si solo deseas mostrar el recuento de descargas, puedes hacer esto:

1

echo '<p>Downloaded: ' . print_r( $plugin_info->downloaded, true ) . ' times</p>';

Podemos seguir ampliando este ejemplo con la comprobación de errores, pero ¿hay una forma mejor? Y la respuesta es sí, con la función plugins_api.

La función plugins_api

La función plugins_api se define en wp-admin/includes/plugin_install.php.

1

<?php

2

3

function plugins_api($action, $args = null) {

4

5

	if ( is_array($args) )

6

		$args = (object)$args;

7

8

	if ( !isset($args->per_page) )

9

		$args->per_page = 24;

10

11

	// Allows a plugin to override the WordPress.org API entirely.

12

	// Use the filter 'plugins_api_result' to merely add results.

13

	// Please ensure that a object is returned from the following filters.

14

	$args = apply_filters('plugins_api_args', $args, $action);

15

	$res = apply_filters('plugins_api', false, $action, $args);

16

17

	if ( false === $res ) {

18

		$url = 'http://api.wordpress.org/plugins/info/1.0/';

19

		if ( wp_http_supports( array( 'ssl' ) ) )

20

			$url = set_url_scheme( $url, 'https' );

21

22

		$request = wp_remote_post( $url, array(

23

			'timeout' => 15,

24

			'body' => array(

25

				'action' => $action,

26

				'request' => serialize( $args )

27

			)

28

		) );

29

30

		if ( is_wp_error($request) ) {

31

			$res = new WP_Error('plugins_api_failed', __( 'An unexpected error occurred. Something may be wrong with WordPress.org or this server&#8217;s configuration. If you continue to have problems, please try the <a href="http://wordpress.org/support/">support forums</a>.' ), $request->get_error_message() );

32

		} else {

33

			$res = maybe_unserialize( wp_remote_retrieve_body( $request ) );

34

			if ( ! is_object( $res ) && ! is_array( $res ) )

35

				$res = new WP_Error('plugins_api_failed', __( 'An unexpected error occurred. Something may be wrong with WordPress.org or this server&#8217;s configuration. If you continue to have problems, please try the <a href="http://wordpress.org/support/">support forums</a>.' ), wp_remote_retrieve_body( $request ) );

36

		}

37

	} elseif ( !is_wp_error($res) ) {

38

		$res->external = true;

39

	}

40

41

	return apply_filters('plugins_api_result', $res, $action, $args);

42

}

43

44

?>

Parámetros

La función plugins_api acepta 2 parámetros: $action y $args:

1. El parámetro $action

Cual puede ser cualquiera de estas 3 opciones a continuación:

1. query_plugins
2. plugin_information
3. hot_tags

2. El parámetro $args

Los argumentos son opcionales y, si se establecen, deben ser un objeto serializado. Los argumentos para cada acción son diferentes y se explican en detalle más adelante en este artículo.

Datos retornados

Los datos retornados dependen de la acción elegida. La acción "plugin_information" devuelve un solo objeto mientras que las otras dos acciones devuelven una matriz de objetos. En caso de un error, como la ausencia de un parámetro de acción o del slug, la función plugin_api también devuelve un objeto con una propiedad única llamada "error" y un valor de (cadena) "Slug no proporcionado" o "acción no implementada".

Un ejemplo de uso de la función plugins_api

Ahora probaremos el mismo ejemplo que usamos anteriormente pero usando la función plugins_api en lugar de wp_remote_post de la API HTTP.

1

<?php

2

3

	/** Prepare our query */

4

	$call_api = plugins_api( 'plugin_information', array( 'slug' => 'custom-favicon' ) );

5

6

	/** Check for Errors & Display the results */

7

	if ( is_wp_error( $call_api ) ) {

8

9

		echo '<pre>' . print_r( $call_api->get_error_message(), true ) . '</pre>';

10

11

	} else {

12

13

		echo '<pre>' . print_r( $call_api, true ) . '</pre>';

14

15

		if ( ! empty( $call_api->downloaded ) ) {

16

17

			echo '<p>Downloaded: ' . print_r( $call_api->downloaded, true ) . ' times.</p>';

18

19

		}

20

21

	}

22

23

?>

El código anterior devolverá los datos de la misma manera que lo hizo nuestro ejemplo anterior. Como puedes ver, esto requiere algunas líneas de código y una conexión a la API del complemento de WordPress.org, la anulación de serialización del objeto devuelto y la verificación inicial de errores se maneja mediante la función plugins_api.

En los dos ejemplos anteriores, solo usamos la acción "plugin_information" y un slug sin otros argumentos, ya que nuestra intención era simplemente recuperar toda la información posible sobre nuestro complemento.

2.1 Argumentos para query_plugins

2.1.1. browse

Muestra la lista similar a http://wordpress.org/plugins/browse/popular/. Los posibles valores son:

• popular
• new
• updated
• top-rated

2.1.2. search

El término a buscar.

2.1.3. tag

Buscar complementos por una etiqueta.

2.1.4. author

Buscar complementos de un autor.

Nota: Entre browse, search, tag y author, solo se puede usar un argumento a la vez.

2.1.5. page (opcional)

El número de la página de los resultados.

2.1.6. per_page (opcional)

La cantidad de resultados que se mostrarán por página.

2.1.7. fields (opcional)

Similar a los campos de plugin_information que se enumeran a continuación.

Ejemplo de una consulta para los complementos más populares:

1

	$call_api = plugins_api( 'query_plugins',

2

		array(

3

			'browse' => 'top-rated',

4

			'page' => '1',

5

			'per_page' => '5',

6

			'fields' => array(

7

				'downloaded' => false,

8

				'rating' => false,

9

				'description' => false,

10

				'short_description' => false,

11

				'donate_link' => false,

12

				'tags' => false,

13

				'sections' => false,

14

				'homepage' => false,

15

				'added' => false,

16

				'last_updated' => false,

17

				'compatibility' => false,

18

				'tested' => false,

19

				'requires' => false,

20

				'downloadlink' => true,

21

			)

22

		)

23

	);

Devuelve una matriz de objetos similar a lo que devuelve plugin_information.

2.2 Argumentos para plugin_information

2.2.1. slug

El slug del complemento para el que necesitamos devolver información.

2.2.2. fields (opcional)

De forma predeterminada, todos los campos del archivo readme.txt se muestran junto con algunos campos adicionales, como el número total de descargas, la calificación y el enlace de descarga. Sin embargo, si solo necesitas obtener unos pocos campos, puedes anular esto enviando una matriz de pares clave/valor, donde el campo es la clave y verdadero/falso como el valor, dependiendo de si deseas que se devuelva el campo o no.

Ejemplo de campos anulados:

1

	/** Prepare our query */

2

	$call_api = plugins_api( 'plugin_information',

3

		array(

4

			'slug' => 'custom-favicon',

5

			'fields' => array(

6

				'downloaded' => false,

7

				'rating' => false,

8

			)

9

		)

10

	);

Los campos que se pueden anular son:

• added
• compatibility
• downloadlink (Nota: la clave real es "download_link", pero para no devolver estos datos, debemos configurar el campo como "downloadlink")
• donate_link
• homepage
• last_updated
• rating
• require
• sections
• tags
• tested

2.3 Argumentos para hot_tags

2.3.1. number

El número de etiquetas que se devolverán. El valor predeterminado es 100.

ejemplo de acción para hot_tags:

1

	/** Prepare our query */

2

	$call_api = plugins_api( 'hot_tags',

3

		array(

4

			'number' => '50',

5

		)

6

	);

Esto devolverá una matriz de objetos con la clave siendo la etiqueta slug y cada objeto contendría:

• Nombre de la etiqueta
• Slug de la etiqueta
• Recuento: la cantidad de complementos marcados con esta etiqueta

Resumen

Internamente, el núcleo de WordPress utiliza la función plugins_api para mostrar una lista de complementos basada en la palabra clave utilizada para la búsqueda, para obtener tus complementos favoritos y también para mostrar información sobre cualquier complemento específico. Al cambiar el parámetro de acción, puedes usar la función para realizar diferentes tareas.

La información sobre la API de WordPress.org no está ampliamente disponible y la razón podría ser para evitar el abuso del sistema, por lo tanto, asegúrate de que tus solicitudes a la API de WordPress.org sean limitadas y se realicen de la manera correcta. Utiliza Transients para almacenar en caché los datos para que no tengas que realizar una solicitud en cada carga de página.

En un futuro tutorial, crearemos un complemento con un código corto para mostrar el recuento de descargas de tu complemento.