It feels like everything we come into contact with is carefully designed: website, phone number, subway map, etc. Even things we used to take for granted: thermostats, smoke detectors, and car dashboards now receive careful user experience treatment.

Design is more than just look and feel: it also needs to consider the various ways users need to interact with our devices/tools/screens/objects.

This also applies to programming.

(Un)Designed Programming

Programming languages ??are a large and complex world. Even PHP, which many programming snobs consider too "simple", is actually a fairly complex combination of functions and classes that behave in very inconsistent ways.

Over the years, the syntax, methods, and naming have evolved across millions of different users and applications. Most tend to reflect the underlying construction inside - not necessarily how you want to use it.

Great moments in API design: jQuery

When I started writing JavaScript around 2006, things were a mess. Here's how I find a tag with a specific class and move it around the 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;

Finish!

jQuery makes JavaScript fun again. In the late 2000s, the impact was so huge that I remember my dad asking me about “something weird” he’d read about in the Wall Street Journal. But despite its huge effect, jQuery doesn't add any "new functionality" to JavaScript. It just breaks down what developers have to do into very clear patterns.

Instead of reinventing how to find content on a page, they leveraged something people already knew: CSS selectors. Then it's just a matter of gathering a bunch of common operations and organizing them into dozens of functions. Let's try the previous example again, now using jQuery:

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

In 2006, I bought a 680 page Ajax book. With jQuery's excellent API, it's almost superseded by this:

$.post();

WordPress API

While API has come to stand for "third-party services," it simply means a programming interface that talks to a system. Just like the Twitter API or the Facebook API, the WordPress API also exists. You wouldn't do a raw database query to create a post, right? You use wp_insert_post.

But many design holes plague the WordPress API. You might use get_the_title but get_the_permalink will generate an error if you use get_permalink . Hey, when you have a decades-long open source project involving thousands of people's code and millions of users: you're going to encounter some quirks.

You can save a lot of time by masking these quirks and writing according to the habits and behaviors of the programmer you're writing for (which is probably you). This is where you can design the right interface for programming the plugins and themes you use every day.

solution

To speed up my work and reduce repetitive tasks, I created libraries to handle the commands and customizations I always needed.

1. Shortcuts for common tasks

Take the source of getting the post thumbnail as an example. It turns out WordPress has no built-in functionality to get thumbnails based on post IDs (only attachment IDs).

This means I often find myself doing this:

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

But there must be a better way!

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: Unpredictable input, predictable output

much better! In fact, you find yourself using it all the time and then sharing it with other developers in the company.

Your friend is in trouble, so he calls you to debug, and you see:

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

It seems he accidentally used get_post instead of get_the_ID. You yelled at him. But wait, why notmake it more acceptable?

Maybe we can adjust our function so that it can take a WP_Post object and still give the user what they expect. Let's get back to the function:

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

So if they send WP_Post objects or an array, your function can still help them get what they need. This is an important part of a successful API: hiding messy internals. You can make separate functions for get_thumbnail_src_by_post_id and get_thumbnail_src_by_wp_post_object.

In fact, it may be preferable for more complex conversions, but you can simplify the interface by routing individual functions to the correct subroutines. No matter what the user sends, this function will always return the string of the image source.

Let's move on: What if they send nothing?

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

我們再次進行了簡化，因此用戶無需發(fā)送帖子，甚至無需發(fā)送帖子 ID。在循環(huán)中時，所需要做的就是：

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

我們的函數(shù)將默認為當(dāng)前帖子的 ID。這正在變成一個非常有價值的功能。為了確保它能很好地發(fā)揮作用，讓我們將它包裝在一個類中，這樣它就不會污染全局命名空間。

/*
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。我將其設(shè)為公共靜態(tài)函數(shù)，因為我希望它可以在任何地方訪問，并且它不會改變：輸入或執(zhí)行不會更改函數(shù)或?qū)ο蟆?

該函數(shù)的最終調(diào)用是：

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

先設(shè)計，后構(gòu)建

讓我們繼續(xù)處理更復(fù)雜的需求。當(dāng)我編寫插件時，我發(fā)現(xiàn)我總是需要生成不同類型的錯誤和/或更新消息。

但是基于事件的語法一直困擾著我：

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

WordPress 遵循這種基于事件的架構(gòu)有很多充分的理由。但這并不直觀，除非您想坐下來記住不同的過濾器和操作。

讓我們將此匹配作為最簡單的用例：我需要顯示管理員通知。我喜歡首先設(shè)計這個 API：我找出在代碼中引用該函數(shù)的最佳方式。我希望它讀起來像這樣：

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");
    }
}

一旦我設(shè)計了端點，我就可以滿足設(shè)計要求：

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>';
        });
    }
}

好多了！現(xiàn)在我不需要創(chuàng)建所有這些額外的函數(shù)或記住瘋狂的鉤子名稱。在這里，我使用 PHP 匿名函數(shù)（也稱為“閉包”），它讓我們可以將函數(shù)直接綁定到操作或過濾器。

這可以讓您避免在文件中出現(xiàn)大量額外的函數(shù)。 use 命令讓我們將參數(shù)從父函數(shù)傳遞到子閉包中。

保持直覺

現(xiàn)在另一位同事打電話給您。她不知道為什么她的管理通知沒有變成紅色：

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

這是因為她正在發(fā)送“紅色”（她希望將盒子變成紅色），而實際上她應(yīng)該發(fā)送觸發(fā)紅色的類名稱。但為什么不讓它變得更容易呢？

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>';
    });
}

我們現(xiàn)在已經(jīng)接受了更多的用戶容忍度，這將使我們在幾個月后回來使用它時更容易分享。

結(jié)論

在構(gòu)建了其中一些之后，以下是我學(xué)到的一些原則，這些原則使這些原則對我和我的團隊真正有用。

1.首先進行設(shè)計，讓函數(shù)的構(gòu)建符合人們想要使用它的方式。

2. 拯救你的鍵盤！為常見任務(wù)創(chuàng)建快捷方式。

3. 提供合理的默認值。

4. 保持最小化。讓您的庫來處理處理。

5. 對輸入要寬容，對輸出要精確。

6. 也就是說，使用盡可能少的函數(shù)參數(shù)，最多四個是一個很好的參數(shù)。之后，您應(yīng)該將其設(shè)為選項數(shù)組。

7. 將您的庫組織成單獨的類，以涵蓋不同的領(lǐng)域（管理、圖像、自定義帖子等）。

8. 包含示例代碼的文檔。

在 Upstatement，我們的 Timber 庫使構(gòu)建主題變得更加容易，而 Jigsaw 提供了節(jié)省時間的快捷方式來自定義每個安裝。

這些工具節(jié)省的時間讓我們可以花更多時間構(gòu)建每個網(wǎng)站或應(yīng)用程序的新的和創(chuàng)新的部分。通過執(zhí)行深奧的命令（例如向管理帖子表添加一列）并制作簡單的界面：我們公司的任何設(shè)計師或開發(fā)人員都可以使用與專業(yè) WordPress 開發(fā)人員相同的能力完全自定義每個網(wǎng)站。