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

</aside>

Aphorism #3

Docs or it didn't happen

#4

A UI is not an API

A User Interface is notan Application Programming Interface

A User is not a Program

A UI is a client of your API

What good is a website without a UI?

Who said you're building a web site?

PHPUnit

(Tests or it didn't happen)

A website is not an API

A website uses an API

An API does not need a web site

You're not done until you havethree implementations

3 implementations?

Unit test

Web services call

Command line

Web site

Aphorism #4

A UI is not an API

#5

You know that saying about standing on the shoulders of giants?
Drupal is standing on a huge pile of midgets.

There are two ways of constructing a software design:
One way is to make it so simple that there are obviously no
deficiencies, and the other way is to make it so complicated that
there are no obvious deficiencies.

— C. A. R. Hoare

The unavoidable price of reliability is simplicity.

— C. A. R. Hoare

Aphorism #7

There is no problem that cannot be solved by adding another layer of abstraction...

except abstraction

#8

Your software has idiosyncrasies,but it's not special.

No one understands Drupalisms, except Drupal developers

(And not even all of them)

No one understands Symfonyisms, except Symfony developers

(And not even all of them)

No one understands PHPisms, except PHP developers

(And not even all of them)

No one understands your system, except you

(And sometimes not even then)

No matter how cool you are,John Resig knows more Javascript than you do.