Aphorisms of API Design

Step 1:

Define your terms

function engage_engine($engine_type) {
    switch ($engine_type) {
        case 'warp':
            // ...
            break;
        case 'hyperspace':
            // ...
            break;
        default:
            throw new UnsupportedSciFiException();
    }
}

function engage_engine($engine_type) {
    switch ($engine_type) {
        case 'warp':
            // ...
            break;
        case 'hyperspace':
            // ...
            break;
        case 'slipstream':
            // ...
            break;
        default:
            throw new UnsupportedSciFiException();
    }
}

function engage_engine(Engine $engine) {
    // ...
    $engine->engage();
}

Beware constants

const ENGINE_WARP = 1;
const ENGINE_HYPERSPACE = 2;

const ENGINE_SLIPSTREAM = 3;

const ENGINE_INFINITE_IMPROBABILITY = 3;

node_load_multiple() Druplicon

Drupal 6

// Fetch one node.
function node_load($nid) {
  $query = "SELECT * FROM node WHERE nid=:nid";
  $record = db_query($query, [':nid' => $nid])->fetchObject();

  $record = load_extra_stuff($record);
  return $record;
}

// Fetch multiple nodes.
function node_load_multiple(array $nids) {
  foreach ($nids as $nid) {
    $nodes[] = node_load($nid);
  }

  return $nodes;
}

Drupal 7

// Fetch one node.
function node_load($nid) {
  $nodes = node_load_multiple([$nid]);
  return reset($nodes);
}

// Fetch multiple nodes.
function node_load_multiple(array $nids) {
  $query = "SELECT * from node WHERE nid IN (:nids)";
  $records = db_query($query, [':nids' => $nids])->fetchAll();

  $records = load_extra_stuff($records);
  return $records;
}

Drupal 6 theme system

function theme($hook) {
  // ...
  if (!isset($hooks[$hook])) {
    return;
  }
  // ...
  return $output;
}

Drupal 7 theme system

function theme($hook, $variables = array()) {
  // ...
  if (!isset($hooks[$hook])) {
    if (!isset($candidate)) {
      log('Theme key "{$hook}" not found.');
    }
    return '';
  }
  // ...
  return $output;
}

Good APIs are picky

class InsertQuery extends Query {
  public function fields(array $fields, array $values = []) {
    // ...
  }
  public function preExecute() {
    if (array_intersect($iFields, $defaultFields)) {
      throw new FieldsOverlapException('...');
    }
    // ...
    return TRUE;
  }
}

Drupal 7 (Module upload system)

abstract class FileTransferFTP extends FileTransfer {
   /**
    * Return an object which can implement the FTP protocol.
    *
    * @param string $jail
    * @param array $settings
    *
    * @return FileTransferFTP
    *    The appropriate FileTransferFTP subclass based on available    
    *    options. If the FTP PHP extension is available, use it.
    */
   static function factory($jail, $settings) { }
}

Date.module (Drupal 6)

/**
 * Getter callback to return date values as datestamp in UTC from the field.
 */
function date_entity_metadata_field_getter($object, array $options,
                                           $name, $obj_type, &$context) { }

No, seriously, WTF?

protected function normalizeCharset($value) {
  switch (mb_detect_encoding($value)) {
    case 'ASCII':
      break;
    case 'UTF-8':
      $value = htmlentities($value, ENT_NOQUOTES);
      $value = html_entity_decode($value, ENT_NOQUOTES, 'UTF-8');
      break;
    case FALSE:
      $value = iconv('Windows-1252', 'UTF-8//TRANSLIT', $value);
      $this->log->warn("Detected Windows-1252 encoding.");
      break;
    default:
      $this->log->warn("Unrecognized character encoding.");
  }
  return $value;
}

WTF is up with UTF-8? And why is FALSE Windows-1252?

protected function normalizeCharset($value) {
  // mb_detect_encoding() in most situations supports only two character sets,
  // ASCII and UTF-8.  However, it is sadly not unusual for incoming data
  // to be in Windows-1252, aka MS Word. We therefore guess that a
  // false/not-found character set is Windows-1252, and try to convert that
  // to UTF-8.
  // Note: The odds of this breaking on some other character encoding besides
  // those three is rather high.

  // ...
}

switch (mb_detect_encoding($value)) {
  // I have absolutely no idea why UTF-8 strings need to be converted
  // from UTF-8 to UTF-8, but if this code is removed many strings end up
  // failing with invalid multi-byte encoding.
  case 'UTF-8':
    // Convert any characters we possibly can to their HTML encoded entities.
    // If we don't specify a character encoding then this should do at least
    // a passingly decent job of detecting it, or at least doesn't care as much
    // as other APIs do.
    $value = htmlentities($value, ENT_NOQUOTES);
    // Convert those HTML entities back into real characters, but this time
    // insist on UTF-8.  This will at worst convert UTF-8 characters back
    // to UTF-8 and at best convert ISO-8859-1 characters to HTML entities and
    // from HTML entities to UTF-8 characters.
    $value = html_entity_decode($value, ENT_NOQUOTES, 'UTF-8');
    break;

// ...

  // A False return from mb_detect_encoding() means that it couldn't
  // figure out what the encoding is.  In a standard configuration mb_* only
  // knows about ASCCI and UTF-8, so that's not especially useful. We will
  // make an assumption that anything else is Windows-1252, aka MS Word legacy
  // garbage. If correct, this will convert $value from Windows-1252 to
  // UTF-8, transliterating where necessary rather than just failing.
  case FALSE:
    $value = iconv('Windows-1252', 'UTF-8//TRANSLIT', $value);
    $this->log->warn("Detected Windows-1252 character encoding.");
    break;
}

Interfaces are your friend

interface LogInterface {
  public method log($message, $severity);
}

PSR-3

namespace Psr\Log;

interface LoggerInterface {
  public function log($level, $message, array $context = array());

  public function emergency($message, array $context = array());
  public function alert($message, array $context = array());
  public function critical($message, array $context = array());
  public function error($message, array $context = array());
  public function warning($message, array $context = array());
  public function notice($message, array $context = array());
  public function info($message, array $context = array());
  public function debug($message, array $context = array());
}

function engage_engine(Engine $engine) {
    // ...
    $engine->engage();
}

Explicit interfaces

namespace Psr\Log;

interface LoggerInterface {
  public function log($level, $message, array $context = array());

  public function emergency($message, array $context = array());
  public function alert($message, array $context = array());
  public function critical($message, array $context = array());
  public function error($message, array $context = array());
  public function warning($message, array $context = array());
  public function notice($message, array $context = array());
  public function info($message, array $context = array());
  public function debug($message, array $context = array());
}

Aphorisms ofAPI Design

Aphorisms of
API Design