Статьи

Связь с API плагинов WordPress.org

В течение последних нескольких недель я размышлял о том, как получить данные о моих плагинах, размещенных на WordPress.org, и отобразить их на моем веб-сайте. Первое, что пришло на ум, было « Соскребание в сети », но, откровенно говоря, это большая работа, похоже, что нужно возвращаться в прошлое, и это не то, что должен делать хороший веб-гражданин. В некоторых случаях это может быть незаконно.

Затем я наткнулся на плагин под названием « Я делаю плагины », разработанный Марком Джакитом, который просто хотел, чтобы я хотел получить данные из файла readme.txt плагина. Это прекрасно работает, но так как WordPress позволяет нам искать плагины непосредственно из серверной части, а также видеть наши любимые плагины, я знал, что есть лучший способ (или путь WordPress), и дальнейший поиск привел меня к API WordPress.org . Нет подробной документации на этой странице, но достаточно, чтобы начать, зная, что есть API, чтобы сделать это более эффективно.


URL-адрес, по которому выполняются все вызовы, связанные с поиском / обновлением плагина: http://api.wordpress.org/plugins/info/1.0/ . Чтобы быстро понять, как это работает, откройте эту ссылку в браузере и добавьте в конец свой плагин, например, http://api.wordpress.org/plugins/info/1.0/custom-favicon/ и посмотрите, что вернулся.

Этот GET-запрос на основе браузера отображал всю информацию о плагине «Custom Favicon» в следующем формате. Заменив последний путь URL на фрагмент вашего плагина, вы сможете увидеть детали, относящиеся к вашему плагину.

01
02
03
04
05
06
07
08
09
10
11
12
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 ap
<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>
 
<h4>My Links</h4>
 
<ul>
 
<li>Twitter @<a href=»https://twitter.com/dreams_media»>harishchouhan</a></li>
 
<li>Google+ <a href=»https://plus.google.com/u/0/103138475844539274387/»>Harish Chouhan</a></li>
 
</ul>

Не очень презентабельно, но, по крайней мере, это хорошее начало для проверки, быстро ли API предоставляет информацию о плагинах, которую мы затем можем отображать так, как нам нравится.

До этого момента большая часть того, что я делал, была основана на случайных испытаниях. Единственный ресурс, который я смог найти, был http://dd32.id.au/projects/wordpressorg-plugin-information-api-docs/, который пытается объяснить различные варианты и аргументы, которые можно использовать при взаимодействии с этим API.

Чтобы связаться с http://api.wordpress.org/plugins/info/1.0/ и получить информацию, вам нужно сделать запрос $POST с двумя вещами:

  1. Post Action — например, $_POST['action']
  2. Post Body — например, $_POST['body'] , который должен быть сериализованным объектом

Возвращенные данные из API являются Объектом во всех случаях (кроме случаев, когда вы посещаете ссылку API из браузера). Даже в случае ошибки возвращаемые данные остаются объектом, но с одним свойством — строкой ошибки.

Моя первая попытка получить информацию о плагине была примерно такой:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
<?php
 
    $args = (object) array( ‘slug’ => ‘custom-favicon’ );
 
    $request = array( ‘action’ => ‘plugin_information’, ‘timeout’ => 15, ‘request’ => serialize( $args) );
 
    $url = ‘http://api.wordpress.org/plugins/info/1.0/’;
 
    $response = wp_remote_post( $url, array( ‘body’ => $request ) );
 
    $plugin_info = unserialize( $response[‘body’] );
 
    echo ‘<pre>’ .
 
?>

Мы объясним код позже, но пока приведенный выше пример кода вернет информацию о нашем плагине в формате, показанном ниже, в случае, если все работает как задумано:

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042
043
044
045
046
047
048
049
050
051
052
053
054
055
056
057
058
059
060
061
062
063
064
065
066
067
068
069
070
071
072
073
074
075
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
092
093
094
095
096
097
098
099
100
101
102
103
stdClass Object
(
    [name] => Custom Favicon
    [slug] => custom-favicon
    [version] => 1.0
    [author] => Dreams Online Themes
    [author_profile] => http://profiles.wordpress.org/hchouhan
    [contributors] => Array
        (
            [hchouhan] => http://profiles.wordpress.org/hchouhan
            [dreamsonline] => http://profiles.wordpress.org/dreamsonline
            [dreamsmedia] => http://profiles.wordpress.org/dreamsmedia
        )
 
    [requires] => 3.5
    [tested] => 3.5.2
    [compatibility] => Array
        (
            [3.6] => Array
                (
                    [1.0] => Array
                        (
                            [0] => 100
                            [1] => 1
                            [2] => 1
                        )
 
                )
 
        )
 
    [rating] => 100
    [num_ratings] => 3
    [downloaded] => 2008
    [last_updated] => 2013-05-27
    [added] => 2013-05-27
    [homepage] => http://www.dreamsonline.net/wordpress-plugins/custom-favicon/
    [sections] => Array
        (
            [description] =>
Now easily upload a favicon and apple touch icon for your WordPress website and dashboard.
 
 
 
Please report any bugs you find via http://www.dreamsonline.net/wordpress-plugins/custom-favicon/
 
 
 
My Links
 
 
 
 
Twitter @harishchouhan
 
Google+ Harish Chouhan
 
 
 
If you love the plugin, please consider rating it and clicking on «it works» button.
 
 
            [installation] =>
 
Upload the directory /custom-favicon/ to the /wp-content/plugins/ directory
 
Activate the plugin through the ‘Plugins’ menu in WordPress
 
Click on «Custom Favicon» sub menu under the Settings menu and upload your favicon
 
 
            [changelog] =>
= 1.0.0
* This is the first version
 
 
            [faq] =>
Take a look at the official «Custom Favicon» FAQ.
 
 
 
You can also visit the support center and start a discussion if needed.
 
 
        )
 
    [download_link] => http://downloads.wordpress.org/plugin/custom-favicon.zip
    [tags] => Array
        (
            [admin] => admin
            [apple-touch] => apple touch
            [apple-touch-icon] => apple touch icon
            [blog] => blog
            [favicon] => favicon
            [icon] => icon
            [iphone] => iphone
            [theme] => theme
            [upload] => upload
            [wordpress] => wordpress
        )
 
    [donate_link] => http://www.dreamsonline.net
)

Если вы просто хотите отобразить счетчик загрузок, вы можете добавить вот так:

1
echo ‘<p>Downloaded: ‘ .

Примечание. Это всего лишь тестовый пример, который не предназначен для использования в реальных проектах, так как здесь нет проверки ошибок. Если slug неверен или соединение с WordPress.org не установлено, приведенный выше код будет отображать ошибки.

Мы можем продолжить расширение этого примера проверкой ошибок, но есть ли лучший способ? И ответ — да , с plugins_api функции plugins_api .


Функция plugins_api определена в wp-admin / includes / plugin_install.php .

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?php
 
function plugins_api($action, $args = null) {
 
    if ( is_array($args) )
        $args = (object)$args;
 
    if ( !isset($args->per_page) )
        $args->per_page = 24;
 
    // Allows a plugin to override the WordPress.org API entirely.
    // Use the filter ‘plugins_api_result’ to merely add results.
    // Please ensure that a object is returned from the following filters.
    $args = apply_filters(‘plugins_api_args’, $args, $action);
    $res = apply_filters(‘plugins_api’, false, $action, $args);
 
    if ( false === $res ) {
        $url = ‘http://api.wordpress.org/plugins/info/1.0/’;
        if ( wp_http_supports( array( ‘ssl’ ) ) )
            $url = set_url_scheme( $url, ‘https’ );
 
        $request = wp_remote_post( $url, array(
            ‘timeout’ => 15,
            ‘body’ => array(
                ‘action’ => $action,
                ‘request’ => serialize( $args )
            )
        ) );
 
        if ( is_wp_error($request) ) {
            $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() );
        } else {
            $res = maybe_unserialize( wp_remote_retrieve_body( $request ) );
            if ( ! is_object( $res ) && ! is_array( $res ) )
                $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 ) );
        }
    } elseif ( !is_wp_error($res) ) {
        $res->external = true;
    }
 
    return apply_filters(‘plugins_api_result’, $res, $action, $args);
}
 
?>

Функция plugins_api принимает 2 параметра: $action и $args :

Который может быть любым из этих 3 вариантов ниже:

  1. query_plugins
  2. plugin_information
  3. hot_tags

Аргументы являются необязательными и, если они установлены, должны быть сериализованным объектом. Аргументы для каждого действия различны и подробно объясняются далее в этой статье.

Возвращаемые данные зависят от выбранного действия. Действие « plugin_information » возвращает один объект, тогда как два других действия возвращают массив объектов. В случае ошибки, такой как отсутствие действия или параметра slug, функция plugin_api также возвращает объект с единственным свойством «error» и значением (строкой) «Slug не предоставлен» или «действие не реализовано».

Теперь мы попробуем тот же пример, который мы использовали ранее, но с использованием функции plugins_api вместо wp_remote_post из HTTP API.

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?php
 
    /** Prepare our query */
    $call_api = plugins_api( ‘plugin_information’, array( ‘slug’ => ‘custom-favicon’ ) );
 
    /** Check for Errors & Display the results */
    if ( is_wp_error( $call_api ) ) {
 
        echo ‘<pre>’ .
 
    } else {
 
        echo ‘<pre>’ .
 
        if ( ! empty( $call_api->downloaded ) ) {
 
            echo ‘<p>Downloaded: ‘ .
 
        }
 
    }
 
?>

Приведенный выше код вернет данные так же, как в предыдущем примере. Как видите, для этого требуется несколько строк кода и подключение к API плагинов WordPress.org, десериализация возвращаемого объекта и начальная проверка ошибок — все выполняется функцией plugins_api .

В обоих приведенных выше примерах мы использовали только действие « plugin_information » и слаг без других аргументов, так как мы собирались просто получить всю возможную информацию о нашем плагине.

Он отображает список, аналогичный http://wordpress.org/plugins/browse/popular/ . Возможные значения:

  • popular
  • new
  • updated
  • top-rated

Термин для поиска.

Поиск плагинов по тегу.

Поиск плагинов от автора.

Примечание. Между browse , search , tag и author может использоваться только один аргумент.

Номер страницы результатов.

Количество результатов для отображения на странице.

Аналогично полям plugin_information перечисленным ниже.

Пример запроса для самых популярных плагинов:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
$call_api = plugins_api( ‘query_plugins’,
       array(
           ‘browse’ => ‘top-rated’,
           ‘page’ => ‘1’,
           ‘per_page’ => ‘5’,
           ‘fields’ => array(
               ‘downloaded’ => false,
               ‘rating’ => false,
               ‘description’ => false,
               ‘short_description’ => false,
               ‘donate_link’ => false,
               ‘tags’ => false,
               ‘sections’ => false,
               ‘homepage’ => false,
               ‘added’ => false,
               ‘last_updated’ => false,
               ‘compatibility’ => false,
               ‘tested’ => false,
               ‘requires’ => false,
               ‘downloadlink’ => true,
           )
       )
   );

Возвращает массив объектов, аналогичный тому, что возвращает plugin_information .

Плагин плагина, для которого нам нужно вернуть информацию.

По умолчанию отображаются все поля из файла readme.txt , а также некоторые дополнительные поля, такие как общее количество загрузок, рейтинг и ссылка для скачивания. Однако, если вам нужно извлечь только несколько полей, вы можете переопределить это, отправив массив пар ключ / значение, где поле является ключом, а true / false в качестве значения, в зависимости от того, хотите ли вы, чтобы поле было возвращено или не.

Пример переопределения полей:

01
02
03
04
05
06
07
08
09
10
/** Prepare our query */
   $call_api = plugins_api( ‘plugin_information’,
       array(
           ‘slug’ => ‘custom-favicon’,
           ‘fields’ => array(
               ‘downloaded’ => false,
               ‘rating’ => false,
           )
       )
   );

Поля, которые могут быть переопределены:

  • added
  • compatibility
  • downloadlink (Примечание: фактический ключ — « download_link », но чтобы не возвращать эти данные, нам нужно установить поле как «ссылка для скачивания»)
  • donate_link
  • homepage
  • last_updated
  • rating
  • require
  • sections
  • tags
  • tested

Количество тегов для возврата. По умолчанию это 100.

hot_tags действия hot_tags :

1
2
3
4
5
6
/** Prepare our query */
   $call_api = plugins_api( ‘hot_tags’,
       array(
           ‘number’ => ’50’,
       )
   );

Это вернет массив объектов с ключом, являющимся тегом slug, и каждый объект будет содержать:

  • Название тэга
  • Tag Slug
  • Количество — Количество плагинов, помеченных этим тегом

Внутренне ядро ​​WordPress использует функцию plugins_api для отображения списка плагинов на основе ключевого слова, используемого для поиска, для получения ваших любимых плагинов, а также для отображения информации о любом конкретном плагине. Изменяя параметр действия, вы можете использовать функцию для выполнения различных задач.

Информация об API WordPress.org не является широко доступной, и причина может заключаться в том, чтобы избежать злоупотребления системой, поэтому убедитесь, что ваши запросы к API WordPress.org ограничены и выполняются правильно. Используйте переходные процессы для кэширования данных, чтобы вам не приходилось делать запросы при каждой загрузке страницы.

В следующем уроке мы создадим плагин с шорткодом для отображения количества загрузок вашего плагина.