Améliorez WordPress : créez des API et des bibliothèques améliorées

On a l'impression que tout ce avec quoi nous entrons en contact est soigneusement conçu : site internet, téléphone, plan du métro, etc. Même les choses que nous tenions autrefois pour acquises : les thermostats, les détecteurs de fumée et les tableaux de bord des voitures font désormais l’objet d’un traitement attentif de l’expérience utilisateur.

Le design ne se limite pas à l'apparence : il doit également prendre en compte les différentes façons dont les utilisateurs doivent interagir avec nos appareils/outils/écrans/objets.

Cela s'applique également à la programmation.

Programmation par (dé)design

Les langages de programmation constituent un monde vaste et complexe. Même PHP, que de nombreux snobs de programmation considèrent comme trop « simple », est en réalité une combinaison assez complexe de fonctions et de classes qui se comportent de manière très incohérente.

La syntaxe, les méthodes et la nomenclature ont évolué au fil des années pour des millions d'utilisateurs et d'applications différents. La plupart ont tendance à refléter la construction sous-jacente à l’intérieur – pas nécessairement la façon dont vous souhaitez l’utiliser.

Grands moments dans la conception d'API : jQuery

​​>

Quand j'ai commencé à écrire du JavaScript vers 2006, les choses étaient en désordre. Voici comment trouver une balise avec une classe spécifique et la déplacer dans le DOM :

var uls = getElementsByTagName("ul");
var classToSearch = "foods";
for (var i = 0; i < uls.length; i++) {
    var classes = uls[i].getClasses();
    for (var j = 0; j < classes.length; j++){
        if (classes[j] == classToSearch){
            myUL = uls[i];
        }
    }
}

var $li = document.createElement('li');
$li.innerHTML = 'Steak';
myUL.innerHTML += $li;

Fait !

jQuery rend JavaScript à nouveau amusant. À la fin des années 2000, l’impact a été si énorme que je me souviens que mon père m’a posé des questions sur « quelque chose de bizarre » qu’il avait lu dans le Wall Street Journal. Mais malgré son énorme effet, jQuery n’ajoute aucune « nouvelle fonctionnalité » à JavaScript. Il décompose simplement ce que les développeurs doivent faire en modèles très clairs.

Plutôt que de réinventer la façon de trouver du contenu sur une page, ils ont exploité quelque chose que les gens connaissaient déjà : les sélecteurs CSS. Il s'agit ensuite simplement de rassembler un ensemble d'opérations communes et de les organiser en dizaines de fonctions. Essayons à nouveau l'exemple précédent, maintenant en utilisant jQuery :

var $li = $('<li>Steak</li>');
$("ul.foods").append($li);

En 2006, j'ai acheté un livre Ajax de 680 pages. Avec l'impressionnante API de jQuery, elle est presque remplacée par ceci :

$.post();

API WordPress

Bien que l'API soit devenue l'acronyme de « Third Party Service », cela signifie simplement une interface de programmation qui communique avec un système. Tout comme l’API Twitter ou l’API Facebook, l’API WordPress existe également. Vous ne feriez pas une requête brute de base de données pour créer une publication, n'est-ce pas ? Vous utilisez wp_insert_post.

Mais de nombreuses failles de conception affectent l’API WordPress. Vous pourriez utiliser get_the_title 但 get_the_permalink 会生成错误，您使用 get_permalink . Hé, lorsque vous avez un projet open source de plusieurs décennies impliquant le code de milliers de personnes et des millions d'utilisateurs : vous allez rencontrer des bizarreries.

Vous pouvez gagner beaucoup de temps en masquant ces bizarreries et en écrivant en fonction des habitudes et des comportements du programmeur pour lequel vous écrivez (qui est probablement vous). C’est ici que vous pouvez concevoir la bonne interface pour programmer les plugins et les thèmes que vous utilisez quotidiennement.

---

Solution

Pour accélérer mon travail et réduire les tâches répétitives, j'ai créé des bibliothèques pour gérer les commandes et les personnalisations dont j'avais toujours besoin.

1. Raccourcis vers les tâches courantes

Prenons l'exemple de l'obtention de la source des miniatures des publications. Il s'avère que WordPress n'a pas de fonctionnalité intégrée pour obtenir des miniatures basées sur les identifiants de publication (uniquement les identifiants de pièce jointe).

Cela signifie que je me retrouve souvent à faire ceci :

$thumb_id = get_post_thumbnail_id( get_the_ID() );
$src = wp_get_attachment_thumb_url( $thumb_id );
echo '<img alt="" src="' . $src . '" />';

Mais il doit y avoir une meilleure façon !

function get_thumbnail_src( $post ){

    $thumb_id = get_post_thumbnail_id( $post );
    $src = wp_get_attachment_thumb_url( $thumb_id );
    
    return $src;
}

echo '<img alt="" src="' . get_thumbnail_src( get_the_ID() ) . '" />';

2 : Entrée imprévisible, sortie prévisible

Beaucoup mieux ! En fait, vous vous retrouvez à l’utiliser tout le temps, puis à le partager avec d’autres développeurs de l’entreprise.

Votre ami est en difficulté, alors il vous appelle pour déboguer, et vous voyez :

echo '<img src="' . get_thumbnail_src( get_post() ) . '">';

On dirait qu'il a accidentellement utilisé get_post 而不是 get_the_ID. Tu lui as crié dessus. Mais attendez, pourquoi ne pas le rendre plus acceptable ?

Peut-être pouvons-nous ajuster notre fonction pour qu'elle puisse prendre un objet WP_Post tout en donnant à l'utilisateur ce qu'il attend. Revenons à la fonction :

function get_thumbnail_src( $post ){

    if ( is_object( $post ) && isset( $post->ID ) ){
    
        $post = $post->ID;
        
    } else if ( is_array( $post ) && isset( $post['ID'] ) ) {
        $post = $post['ID'];
    }
    
    $thumb_id = get_post_thumbnail_id( $post );
    $src = wp_get_attachment_thumb_url( $thumb_id );
    
    return $src;
    
}

Donc, s'ils envoient WP_Post 对象或一个数组，您的函数仍然可以帮助他们获得所需的内容。这是成功 API 的重要组成部分：隐藏混乱的内部结构。您可以为 get_thumbnail_src_by_post_id 和 get_thumbnail_src_by_wp_post_object. un objet

ou

un tableau, votre fonction peut toujours les aider à obtenir ce dont ils ont besoin. Il s’agit d’un élément important du succès d’une API : cacher les éléments internes désordonnés. Vous pouvez créer des fonctions distinctes pour get_thumbnail_src_by_post_id et get_thumbnail_src_by_wp_post_object.

En fait, cela peut être préférable pour des conversions plus complexes, mais vous pouvez simplifier l'interface en acheminant les fonctions individuelles vers les sous-programmes appropriés. Peu importe ce que l'utilisateur envoie, cette fonction renverra toujours la chaîne de la source de l'image.

🎜 Passons à autre chose : et s'ils n'envoient rien ? 🎜

3。合理的默认值

function get_thumbnail_src( $post = false ) {

    if (  false === $post ) {
        $post = get_the_ID();
    } else if ( is_object( $post ) && isset( $post->ID ) ) {
        $post = $post->ID;
    } else if ( is_array( $post ) && isset( $post['ID'] ) ) {
        $post = $post['ID'];
    }
    
    $thumb_id = get_post_thumbnail_id( $post );
    $src = wp_get_attachment_thumb_url( $thumb_id );
    
    return $src;
    
}

我们再次进行了简化，因此用户无需发送帖子，甚至无需发送帖子 ID。在循环中时，所需要做的就是：

echo '<img src="'.get_thumbnail_src().'" />';

我们的函数将默认为当前帖子的 ID。这正在变成一个非常有价值的功能。为了确保它能很好地发挥作用，让我们将它包装在一个类中，这样它就不会污染全局命名空间。

/*
Plugin Name: JaredTools
Description: My toolbox for WordPress themes.
Author: Jared Novack
Version: 0.1
Author URI: http://upstatement.com/
*/

class JaredsTools {

    public static function get_thumbnail_src( $post = false ) {
    
        if (false === $post ) {
            $post = get_the_ID();
        } else if ( is_object( $post ) && isset( $post->ID ) ) {
            $post = $post->ID;
        } else if ( is_array( $post ) && isset( $post['ID'] ) ) {
            $post = $post['ID'];
        }
        
        $thumb_id = get_post_thumbnail_id( $post );
        $src = wp_get_attachment_thumb_url( $thumb_id );
        
        return $src;
        
    }
    
}

并且请不要在您的类前面添加 WP。我将其设为公共静态函数，因为我希望它可以在任何地方访问，并且它不会改变：输入或执行不会更改函数或对象。

该函数的最终调用是：

echo '<img src="'.JaredsTools::get_thumbnail_src().'">';

先设计，后构建

让我们继续处理更复杂的需求。当我编写插件时，我发现我总是需要生成不同类型的错误和/或更新消息。

但是基于事件的语法一直困扰着我：

add_action( 'admin_notices', 'show_my_notice');
functon show_my_notice(){
    echo '<div class="updated"><p>Your thing has been updated</p></div>';
}

WordPress 遵循这种基于事件的架构有很多充分的理由。但这并不直观，除非您想坐下来记住不同的过滤器和操作。

让我们将此匹配作为最简单的用例：我需要显示管理员通知。我喜欢首先设计这个 API：我找出在代码中引用该函数的最佳方式。我希望它读起来像这样：

function thing_that_happens_in_my_plugin($post_id, $value){
    $updated = update_post_meta($post_id, $value);
    if ($updated){
        JaredsTools::show_admin_notice("Your thing has been updated")
    } else {
        JaredsTools::show_admin_notice("Error updating your thing", "error");
    }
}

一旦我设计了端点，我就可以满足设计要求：

class JaredsTools {
    public static function show_admin_notice($message, $class = 'updated'){
        add_action('admin_notices', function() use ($message, $class){
            echo '<div class="'.$class.'"><p>'.$message.'</p></div>';
        });
    }
}

好多了！现在我不需要创建所有这些额外的函数或记住疯狂的钩子名称。在这里，我使用 PHP 匿名函数（也称为“闭包”），它让我们可以将函数直接绑定到操作或过滤器。

这可以让您避免在文件中出现大量额外的函数。 use 命令让我们将参数从父函数传递到子闭包中。

保持直觉

现在另一位同事打电话给您。她不知道为什么她的管理通知没有变成红色：

JaredsTools::show_admin_notice("Error updating your thing", "red");

这是因为她正在发送“红色”（她希望将盒子变成红色），而实际上她应该发送触发红色的类名称。但为什么不让它变得更容易呢？

public static function show_notice( $message, $class = 'updated' ) {

    $class = trim( strtolower( $class ) );
    if ( 'yellow' == $class ) {
        $class = 'updated';
    }
    
    if ('red' == $class ) {
        $class = 'error';
    }
    
    add_action( 'admin_notices', function() use ( $text, $class ) {
        echo '<div class="'.$class.'"><p>' . $text . '</p></div>';
    });
}

我们现在已经接受了更多的用户容忍度，这将使我们在几个月后回来使用它时更容易分享。

---

结论

在构建了其中一些之后，以下是我学到的一些原则，这些原则使这些原则对我和我的团队真正有用。

1.首先进行设计，让函数的构建符合人们想要使用它的方式。

2. 拯救你的键盘！为常见任务创建快捷方式。

3. 提供合理的默认值。

4. 保持最小化。让您的库来处理处理。

5. 对输入要宽容，对输出要精确。

6. 也就是说，使用尽可能少的函数参数，最多四个是一个很好的参数。之后，您应该将其设为选项数组。

7. 将您的库组织成单独的类，以涵盖不同的领域（管理、图像、自定义帖子等）。

8. 包含示例代码的文档。

在 Upstatement，我们的 Timber 库使构建主题变得更加容易，而 Jigsaw 提供了节省时间的快捷方式来自定义每个安装。

这些工具节省的时间让我们可以花更多时间构建每个网站或应用程序的新的和创新的部分。通过执行深奥的命令（例如向管理帖子表添加一列）并制作简单的界面：我们公司的任何设计师或开发人员都可以使用与专业 WordPress 开发人员相同的能力完全自定义每个网站。

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!