Berkomunikasi dengan WordPress.org Plugin API

Selama beberapa minggu terakhir saya bertanya-tanya tentang bagaimana cara menarik data tentang plugin saya yang dihosting di WordPress.org dan menampilkannya di situs web saya. Hal pertama yang muncul dalam pikiran adalah "Web Scraping" tapi sejujurnya ini adalah pekerjaan yang banyak, terasa seperti kembali ke masa lalu, dan bukan sesuatu yang seharusnya dilakukan oleh seorang warga web yang baik. Dalam beberapa kasus, itu bisa ilegal.

Saya kemudian menemukan sebuah plugin bernama "I Make Plugins", yang dikembangkan oleh Mark Jaquith, yang hanya ingin saya inginkan dengan mengambil data dari file readme.txt dari sebuah plugin. Ini berfungsi dengan baik tetapi karena WordPress memungkinkan kita untuk mencari plugin langsung dari backend dan juga untuk melihat plugin favorit kami, saya tahu ada cara yang lebih baik (atau The Wordpress Way) dan pencarian lebih lanjut membawa saya ke WordPress.org API. Tidak ada dokumentasi mendetail di halaman ini, tetapi cukup untuk mulai mengetahui bahwa ada API untuk melakukan ini secara lebih efisien.

WordPress.org plugin API

URL tempat semua pencarian plugin / pembaruan panggilan terkait dilakukan adalah http://api.wordpress.org/plugins/info/1.0/. Untuk mendapatkan ide cepat tentang cara kerjanya, buka tautan ini di browser dan tambahkan slug plugin Anda di bagian akhir, mis. http://api.wordpress.org/plugins/info/1.0/custom-favicon/ dan lihat apa yang dikembalikan.

Permintaan GET berbasis browser ini menampilkan semua informasi plugin untuk plugin "Custom Favicon" dalam format di bawah ini. Dengan mengganti jalur terakhir URL dengan siput plugin Anda, Anda akan dapat melihat detail khusus untuk plugin Anda.

1

2

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>

3

<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>

4

5

<h4>My Links</h4>

6

7

<ul>

8

9

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

10

11

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

12

13

</ul>

Tidak terlalu nyata, tapi hei, setidaknya ini adalah awal yang baik untuk menguji apakah API memberikan informasi plugin dengan cepat, yang kemudian kami dapat menampilkan cara yang disukai.

Sampai titik ini, sebagian besar dari apa yang saya lakukan hanya didasarkan pada uji coba acak. Satu-satunya sumber yang bisa saya temukan adalah http://dd32.id.au/projects/wordpressorg-plugin-information-api-docs/ yang mencoba menjelaskan berbagai opsi dan argumen yang dapat digunakan saat berkomunikasi dengan API ini.

Jadi bagaimana Cara Kerjanya?

Untuk berkomunikasi dengan http://api.wordpress.org/plugins/info/1.0/ dan dapatkan kembali informasi yang Anda perlukan untuk membuat permintaan $POST dengan 2 hal:

1. Post Action - seperti, $_POST['action']
2. Post Body - seperti, $_POST['body'], yang harus menjadi objek serial

Data yang dikembalikan dari API adalah Objek dalam semua kasus (kecuali saat mengunjungi tautan API dari browser). Bahkan dalam kasus kesalahan, data yang dikembalikan masih merupakan objek tetapi dengan satu properti, sebuah error string.

Upaya pertama saya untuk mendapatkan kembali informasi plugin adalah sesuatu seperti contoh di bawah ini:

Contoh Retriving Plugin Information Menggunakan wp_remote_post HTTP API

1

2

<?php

3

4

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

5

6

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

7

8

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

9

10

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

11

12

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

13

14

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

15

16

?>

Kita akan menjelaskan kode tersebut nanti tetapi untuk sekarang kode contoh di atas akan mengembalikan informasi tentang plugin dalam format yang ditunjukkan di bawah ini, dalam hal semuanya bekerja sebagaimana dimaksud:

1

2

stdClass Object

3

(

4

    [name] => Custom Favicon

5

    [slug] => custom-favicon

6

    [version] => 1.0

7

    [author] => Dreams Online Themes

8

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

9

    [contributors] => Array

10

        (

11

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

12

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

13

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

14

        )

15

16

    [requires] => 3.5

17

    [tested] => 3.5.2

18

    [compatibility] => Array

19

        (

20

            [3.6] => Array

21

                (

22

                    [1.0] => Array

23

                        (

24

                            [0] => 100

25

                            [1] => 1

26

                            [2] => 1

27

                        )

28

29

                )

30

31

        )

32

33

    [rating] => 100

34

    [num_ratings] => 3

35

    [downloaded] => 2008

36

    [last_updated] => 2013-05-27

37

    [added] => 2013-05-27

38

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

39

    [sections] => Array

40

        (

41

            [description] =>

42

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

43

44

45

46

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

47

48

49

50

My Links

51

52

53

54

55

Twitter @harishchouhan

56

57

Google+ Harish Chouhan

58

59

60

61

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

62

63

64

            [installation] =>

65

66

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

67

68

Activate the plugin through the 'Plugins' menu in WordPress

69

70

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

71

72

73

            [changelog] =>

74

= 1.0.0

75

* This is the first version

76

77

78

            [faq] =>

79

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

80

81

82

83

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

84

85

86

        )

87

88

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

89

    [tags] => Array

90

        (

91

            [admin] => admin

92

            [apple-touch] => apple touch

93

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

94

            [blog] => blog

95

            [favicon] => favicon

96

            [icon] => icon

97

            [iphone] => iphone

98

            [theme] => theme

99

            [upload] => upload

100

            [wordpress] => wordpress

101

        )

102

103

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

104

)

Jika Anda hanya ingin menampilkan jumlah unduhan, Anda dapat menambahkannya seperti ini:

1

2

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

Kita dapat terus memperluas contoh ini dengan pemeriksaan kesalahan tetapi apakah ada cara yang lebih baik? Dan jawabannya adalah ya, dengan fungsi plugins_api.

Fungsi Plugins_api

Fungsi plugins_api didefinisikan dalam wp-admin/includes/plugin_install.php.

1

2

<?php

3

4

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

5

6

	if ( is_array($args) )

7

		$args = (object)$args;

8

9

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

10

		$args->per_page = 24;

11

12

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

13

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

14

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

15

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

16

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

17

18

	if ( false === $res ) {

19

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

20

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

21

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

22

23

		$request = wp_remote_post( $url, array(

24

			'timeout' => 15,

25

			'body' => array(

26

				'action' => $action,

27

				'request' => serialize( $args )

28

			)

29

		) );

30

31

		if ( is_wp_error($request) ) {

32

			$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() );

33

		} else {

34

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

35

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

36

				$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 ) );

37

		}

38

	} elseif ( !is_wp_error($res) ) {

39

		$res->external = true;

40

	}

41

42

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

43

}

44

45

?>

Parameter

Fungsi plugins_api menerima 2 parameter: $action dan $args:

1. Parameter $action

Yang bisa menjadi salah satu dari 3 opsi di bawah ini:

1. query_plugins
2. plugin_information
3. hot_tags

2 Parameter $args.

Argumen bersifat opsional, dan jika diatur, harus menjadi objek serial. Argumen untuk setiap tindakan berbeda dan dijelaskan secara terperinci nanti dalam artikel ini.

Data yang dikembalikan

Data yang dikembalikan tergantung pada tindakan yang dipilih. Tindakan "plugin_information" mengembalikan satu objek sedangkan dua tindakan lainnya mengembalikan array objek. Dalam kasus kesalahan seperti tidak adanya tindakan atau parameter slug, fungsi plugin_api juga mengembalikan objek dengan "kesalahan" satu properti dan nilai (string) "Slug tidak disediakan" atau "tindakan tidak dilaksanakan".

Contoh menggunakan fungsi plugins_api

Sekarang kita akan mencoba contoh yang sama yang kita gunakan sebelumnya tetapi menggunakan fungsi plugins_api daripada wp_remote_post dari HTTP API.

1

2

<?php

3

4

	/** Prepare our query */

5

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

6

7

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

8

	if ( is_wp_error( $call_api ) ) {

9

10

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

11

12

	} else {

13

14

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

15

16

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

17

18

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

19

20

		}

21

22

	}

23

24

?>

Kode di atas akan mengembalikan data dengan cara yang sama seperti contoh sebelumnya. Seperti yang Anda lihat, ini membutuhkan beberapa baris kode dan koneksi ke WordPress.org Plugin API, unserializing objek yang dikembalikan dan pemeriksaan kesalahan awal semua ditangani oleh fungsi plugins_api.

Dalam kedua contoh di atas, kita hanya menggunakan tindakan "plugin_information" dan siput tanpa argumen lain karena niat kita hanya untuk mengambil semua informasi yang mungkin tentang plugin.

2.1 Argumen untuk query_plugins

2.1.1. browse

Ini menampilkan daftar yang mirip dengan http://wordpress.org/plugins/browse/popular/. Nilai yang mungkin adalah:

• popular
• new
• updated
• top-rated

2.1.2. search

Istilah yang dicari.

2.1.3. tag

Cari plugin dengan tag.

2.1.4. author

Cari plugin dari seorang penulis.

Catatan: Antara browse, search, tag dan author hanya satu argumen dapat digunakan pada suatu waktu.

2.1.5. page (opsional)

Nomor halaman hasil.

2.1.6. per_page (opsional)

Jumlah hasil yang ditampilkan per halaman.

2.1.7. fields (opsional)

Mirip dengan bidang plugin_information yang tercantum di bawah ini.

Contoh query untuk plugin paling populer:

1

2

	$call_api = plugins_api( 'query_plugins',

3

		array(

4

			'browse' => 'top-rated',

5

			'page' => '1',

6

			'per_page' => '5',

7

			'fields' => array(

8

				'downloaded' => false,

9

				'rating' => false,

10

				'description' => false,

11

				'short_description' => false,

12

				'donate_link' => false,

13

				'tags' => false,

14

				'sections' => false,

15

				'homepage' => false,

16

				'added' => false,

17

				'last_updated' => false,

18

				'compatibility' => false,

19

				'tested' => false,

20

				'requires' => false,

21

				'downloadlink' => true,

22

			)

23

		)

24

	);

Mengembalikan larik objek yang mirip dengan apa yang dikembalikan plugin_information.

2.2 Argumen untuk plugin_information

2.2.1. slug

The slug dari plugin yang dibutuhkan untuk mengembalikan informasi.

2.2.2. fields (opsional)

Secara default semua bidang dari readme.txt ditampilkan bersama dengan beberapa bidang tambahan seperti jumlah total unduhan, peringkat dan tautan unduhan. Namun, jika Anda hanya perlu mengambil beberapa bidang saja, Anda dapat menimpanya dengan mengirimkan serangkaian pasangan kunci / nilai, di mana bidang adalah kunci dan benar / salah sebagai nilai tergantung pada apakah Anda ingin bidang tersebut dikembalikan atau tidak.

Contoh override bidang:

1

2

	/** Prepare our query */

3

	$call_api = plugins_api( 'plugin_information',

4

		array(

5

			'slug' => 'custom-favicon',

6

			'fields' => array(

7

				'downloaded' => false,

8

				'rating' => false,

9

			)

10

		)

11

	);

Fields yang dapat diganti adalah:

• added
• compatibility
• downloadlink (Catatan: bahwa kunci sebenarnya adalah "download_link" tetapi untuk tidak mengembalikan data ini, kita perlu mengatur field sebagai "tautan unduhan")
• donate_link
• homepage
• Last_updated
• rating
• require
• sections
• tags
• tested

2.3 Argumen untuk hot_tags

2.3.1. number

Jumlah tag untuk dikembalikan. Standarnya adalah 100.

contoh tindakan hot_tags:

1

2

	/** Prepare our query */

3

	$call_api = plugins_api( 'hot_tags',

4

		array(

5

			'number' => '50',

6

		)

7

	);

Ini akan mengembalikan array objek dengan kunci yang menjadi slug tag dan setiap objek akan berisi:

• Tag Name
• Tag Slug
• Count - jumlah plugin yang ditandai dengan tag ini

Summary

Secara internal inti WordPress menggunakan fungsi plugins_api untuk menampilkan daftar plugin berdasarkan kata kunci yang digunakan untuk pencarian, untuk mengambil plugin favorit Anda dan juga untuk menampilkan informasi tentang plugin tertentu. Dengan mengubah parameter tindakan, Anda dapat menggunakan fungsi untuk melakukan tugas yang berbeda.

Informasi tentang WordPress.org API tidak tersedia secara luas dan alasannya mungkin adalah untuk menghindari penyalahgunaan sistem, maka pastikan permintaan Anda ke WordPress.org API terbatas dan dilakukan dengan cara yang benar. Gunakan Transien untuk menyimpan data sehingga Anda tidak perlu membuat permintaan pada setiap pemuatan halaman.

Dalam tutorial mendatang kita akan membuat plugin dengan shortcode untuk menampilkan jumlah unduhan plugin Anda.