Back before horses were invented, the tiny kingdom of Schadenfreude was ruled by good King Floyd and Queen Tillie, who were worried that their son Prince Roscoe would never find a wife. In the neighboring kingdom of Punim, King Marvin had a beautiful daughter named Shayna who was an excellent marriage prospect. She was clever, beautiful, and had massive tracts of land. Floyd and Tillie gathered up the royal retainers and ventured out to see King Marvin.

Schadenfreude and Punim were on good terms, although Schadenfreude's diplomats always seemed a little too happy when things went wrong in Punim. King Marvin agreed that the marriage between Roscoe of Schadenfreude and Shayna of Punim would be a good thing.

Now, though Punim was a mostly happy kingdom on its face, there was one source of unhappiness. Only a male of the royal blood could inherit the throne. Since King Marvin had no male children, there was great infighting among his seventeen brothers about who would take the throne when Marvin died. As soon as they were married, it fell upon Roscoe and Shayna to have a son as soon as they could, so that there would be an heir to King Marvin's throne and end the fighting.

The fates smiled upon the couple and Shayna was soon pregnant, but though they visited wizard after wizard, none could say for sure whether Shayna would have a boy or a girl. Shayna was 7 months along when her father, King Marvin, fell gravely ill. His doctors gave him three months to live and his brothers began jockeying for power. But none could make a move until it was known if Princess Shayna and Prince Roscoe's child was a boy or a girl.

Every prince sent an ambassador to the court of King Floyd. Each ambassador had the same request "send your swiftest messenger on your strongest horse to tell my master if the child is a girl. You will be richly rewarded." Since horses had not yet been invented, Floyd found this request puzzling, yet every ambassador made it and Floyd was left in an uncomfortable situation. If he favored one brother over another, that brother might become king and reward him, but that brother might also fail, and that could leave Floyd on bad terms with the brother who succeeded.

Schadenfreude could not afford a spy corps that could return enough information for Floyd to judge which brother he should ally with, so he called for Alan, the royal wizard. Alan listened intently to King Floyd's dilemma and proposed a solution. "I will create a special magic mirror for this birth()." Alan called it "birth()" because the parentheses to him looked like the opening through which the baby would come.

"Every wizard whose master is interested in knowing the results of the birth() can use their magic communication objects to register their intent with the magic mirror. This way we do not have to construct the mirror with foreknowledge of all the other magic objects it must notify. When birth() happens, the mirror will merely run through the list of objects that have registered with it and transmit the event to them. This will happen so quickly, no one prince will be able to claim we showed favor to another."

King Floyd thought this a marvelous solution and commissioned the wizard Alan to build such a mirror. He completed it quickly, using methods he had previously developed to speed its construction. The ambassadors were all sent back to their princes with instructions on how to register with the magic mirror. And when the baby was born, the magic mirror sent "child = boy" to all the registered objects.

Because he made so many brothers unhappy, they named him Joseph. And when he grew up, he invented horses.

The End

The first place I recall encountering the observer pattern was not in PHP, but in JavaScript. If you've ever set a listener to fire when an event happened, you've used the observer pattern. Functions or methods are registered with an object so that when it experiences a specific event, it "notifies" the registered functions or methods by calling them.

This is a great example of loose coupling. The object that implements the "subject" part of the observer pattern has no foreknowledge of the other classes/objects that will observe it, so they're not hardcoded into the class. Instead, they're registered or attached as needed at runtime. Going back to JavaScript and HTML, I can create this button:

<button id="button1" type="button" value="My Button" onClick="myFunction();"/>

That's a tightly coupled button that DOESN'T implement the observer pattern, because the function the button will call is hardcoded into the button's HTML. On the other hand, I can register a listener for the button's click event very easily with jQuery.

<script type="text/javascript">
	$("#button1").click(function(){
		// some code goes here
	});
</script>
<button id="button1" type="button" value="My Button"/>

Though it's a little more typing to set the listener instead of an onClick handler in the button's instantiation, you can set multiple listeners that will all fire on the click without changing the HTML.

I'm sorry I didn't give sample code for an observer pattern in PHP, but web user interfaces are so observer oriented, it just felt like I had to go with the JS example. Plus, I don't know about you, but I don't have the option of being a "pure" PHP coder. I have to work with JavaScript and jQuery periodically, so mixing things up doesn't hurt as far as I'm concerned.

If you really want a PHP implementation, check out the documentation for the SplSubject interface. The SPL (Standard PHP Library) bakes in some language level support for the observer pattern with the SplSubject and SplObserver interfaces.

Nopw to today's tip...

One of the projects making my life hectic was that project to redirect API calls into a database during some scheduled downtime and then pull them all out and run them against the API when it was back up. What one manager had predicted would be 20-40 API calls turned out to be 708. But when it came time to pull them out of the database, some were failing. Turned out that the column holding the data I would pass to the API was being truncated at 256 characters.

Back up to my earliest days of database design where I was taught that using a varchar data type was better than using a text data type because it used less memory and was more indexable. I should probably double check if that's still true, but that's what I read. So though I knew I might store more than 256 chars in that field, I was using Microsoft Sequel Server and I'd read that the nvarchar type could take up to 8,000 characters. So I went with a nvarchar data type with a max size of 2,048 characters for this column.

If I ran my stored process to retrieve data using Server Management Studio, everything came back in full. But in PHP, the results were getting truncated to 256 characters. I pinged the director of web development to see if he knew why and he said "no, but our database class is just a wrapper for Pear DB. Maybe you can start there." I did a little googling and found out a fun fact.

Pear DB treats nvarchar like varchar, and though Microsoft lets you store up to 8,000 characters, Pear DB limits what it returns to 256 characters. Now, with 708 rows already stored and this being a production server that I don't have any sort of admin access to, restructuring a live table was not going to be an efficient solution. But I kept googling and found out a fun trick... I could rewrite my SELECT query to recast the nvarchar data type as a text data type in the output.

So I went from:

SELECT id, method, data, processed FROM [table]

to...

SELECT id, method, CONVERT(TEXT,data) as data, processed FROM [table]

That simple. I updated my retrieval routine with the altered query and no more truncation.

Lesson of the day: Be careful with your MSSQL data types when working with Pear DB.

So today's tip is about rawurlencode().

Encoding is useful when you need to compose a GET URL that has parameters in it containing characters that are technically illegal to use in a URL (like spaces) or that might mess up your query string (like ampersands and question marks). This is where urlencode() always seemed to come in handy.

$customername = "Ted Fischer";
$customeraddress = "124 Main St.";
$closestXstreets = "Main & Vincent";

$displayclientlocationURL = 
   "http://spgulhankmeder.com/mapit?name=" . urlencode($customername).
   "&address=" . urlencode($customeraddress) .
   "&xstreets=" . urlencode($closestXstreets);

echo "<a href=\"$displayclientlocationURL\">Map it</a>";

This returns:

<a href="http://spgulhankmeder.com/mapit?name=Ted+Fischer&address=124+Main+St.&xstreets=Main+%26+Vincent">Map it</a>

All the spaces are converted to plusses and the ampersand that's part of content instead of control has been converted to %26.

That might be okay, but I've found out the hard way that not every receiving server is going to convert those pluses back to spaces. Some don't back-convert them, particularly if they're not running PHP. See the spec in RFC 3986 says that spaces should be rendered as %20, not as +. If you're in a mixed environment and can't be sure the receiving server will treat pluses as spaces, using rawurlencode will get you the following:

<a href="http://spgulhankmeder.com/mapit?name=Ted%20Fischer&address=124%20Main%20St.&xstreets=Main%20%26%20Vincent">Map it</a>

And that will be understood and decoded properly in more places in my experience. I've known about urlencode() for a while now, but it's raw version is new to me and now I'm sharing it.

Long, long ago and far, far away, a king commissioned all his wizards to create a single repository of all the kingdom's knowledge. In the kingdom's language, their word for knowledge was "data" and this repository was supposed to form the base of all knowledge, so they called it the Great Database. It took the form of a giant bucket in which all the kingdom's knowledge was stored as a pool of information, and it was levitated over the sands of the Great Desert.

To use the Great Database, one would throw a large hose up over the rim of the tub to connect with the pool. They could then add to, retrieve, or even update the knowledge in the pool. In early tests, the magicians made this work flawlessly and the king was overjoyed at his Great Database. He threw a great party to celebrate its creation.

Every school in the kingdom was invited to send one class. Many classes wanted to use the Great Database, but when all their members each threw up a hose, the great weight of so many connections brought the Great Database crashing down. The magicians were called and worked furiously to detach all the hoses and raise the Great Database once more.

To solve this problem of too many hoses, they limited each class to one hose and appointed one member the keeper of the hose. But some classes took a long time to complete all their members' queries of the Great Database because they would throw up the hose before each question and then pull it down after, wasting time and tiring their keeper of the hose. And every time a new class came along, the magicians had to spend time training one of its members in casting and retrieving the hose.

Finally, Ignatz the Fetid conceived of an idea... a single hose. It would be cast by a worker who would manage it and bring it to each class when requested. When no classes needed it, it could be disconnected, but when called by a class, it would be left connected until all the classes' sessions were done and they were cleared.

Because it had to do much work and was rather large, this hose was very heavy. It weighed exactly 2,000 pounds. Since it did not weigh more or less, it was declared that it weighed a "single ton," and that became its name. Over the years, the words ran together and today we know it as the Singleton.

The Singleton pattern is a simple form of resource management. Every time you create a resource like a database handle or a filestream, there's a cost in overhead. If you create multiple, you create more overhead. And whenever you release one before you're done, then have to re-establish it, the repetition slows down execution.

So we create a class that manages that resource. Whenever another class requests the resource, the class checks to see if it exists, and if not, it creates it. Then, until execution ends, every class that needs the resource gets it passed to them instead of getting a new one created. By sharing the resource through this manager, the cost of redundant resources or repeated creation/release of resources is mostly eliminated.

Here's a simple singleton:

class Database{

    private static $instance;
    private $db;

    private function __construct(){
        /**
         *Create the database connection
         */
        [database connection information]
        $this->db = mysql_connect($dbserver, 
           $userdbl, $userdba) or die("could not connect to database");
        mysql_select_db([name of db],$this->db);
    }

    public static function getInstance(){
	if(!self::$instance){
	    self::$instance = new Database();
        }
        return self::$instance;
    }
}

Now this isn't quite the same as in the IBM article. I saw this way of implementing a singleton in another article and liked the idea of making the __construct() method private. That way, no one can instantiate the Database class as an object except the class itself. And because you're passing the Database object instead of simply passing the database connection handle, you can implement some ORM as methods in the object.

Anyhow, I hope you enjoyed this. If you did, please leave a comment, tweet about it, or link to it from your favorite mailing list or social media site.

Henry had a company that made these new fangled things called automobiles. Now automobiles were made up of a lot of parts, and one of the primary parts they needed was axles. Each axle needed to implement two methods: attachWheels() and turn().

Steven had a company that made axles. He supplied axles to Henry's assembly line. When Henry first designed his automobile, he thought an axle from a solid piece of hickory would do a really good job. So he printed up a bunch of ordering forms that specified new HickoryWoodAxle() as the part to be used.

One day, over drinks at the country club, Steven was talking with Andrew. Andrew told him "I can supply you with birch at half the cost of hickory and it will be just as strong." Knowing it would be wrong to change the wood without approval, Steven called Henry, who was busy trying to hit rubber frogs into a copper spitoon with a croquet mallet. "Yeah, yeah, whatever," Henry said.

Steven went into production immediately, making axles out of birch. Feeling it would be dishonest to call them HickoryWoodAxle(), he changed the part ID to BirchWoodAxle(). Henry, however, had caught a ship to Bora Bora where he was under the delusion that he was headlining a three-act musical tribute to molybdenum in the basement of an opium den, and forgot to inform his plant to change the order form.

The next time Henry's plant requested a HickoryWoodAxle(), the shipping manager at Steven's plant looked in inventory and said "we don't have any of those." He refused to send Henry's plant a HickoryWoodAxle(), and Henry's plant had to shut down. If only they'd known to order a BirchWoodAxle(), they could have kept production plugging along.

Henry's stockholders met in secret and sent a team of elite Jesuit ninjas to extract Henry from the steppes of Mongolia where he'd become the alpha male in a herd of Yak. When he got back, he called Steven and chewed him out. Steven argued back that Henry should have told his procurement staff of the change. The argument got so heated that they met and had a forty-seven-hour thumb wrestling competition to settle it, but that ended in a draw.

Still, during that competition, they got to talking. "Why does it have to be so difficult," Henry asked. "All I want is an axle. All it has to do is attachWheels() and turn(). I don't care what material you use."

As their thumbs darted back and forth in an intricate dance better explained by a color commentator, their lawyers drew up a contract, defining how Steven and Henry would interface. At Steven's factory, if they got in an order for a new axle(), so long as it could attachWheels() and turn(), that would be good enough. And that way Steven could change his tooling, his materials, or even ship the production overseas. So long as Henry got an axle() that behaved as expected, he'd be happy.

So the Factory pattern, as I understand it, is one of the most basic implementations of Loose Coupling. That's where too much knowledge is a dangerous thing. Through the order forms, Henry's assembly line was coded to request a HickoryWoodAxle() object. Every time Steven's plant changed the material, and thus the name of the product class, Henry's assembly line would have to change its order form or the whole system could break down.

So they negotiated an interface...

interface IAxle {
	function attachWheels();
	function turn();
}

Using that interface as a guide, Steven could create his axle factory that would send an Axle, every time someone sent it a buy order.

class Axle implements IAxle {
	private $_material = "ceramic";
	
	public function attachWheels(){
		return "Wheels attached";
	}
	
	public function turn(){
		return "Turning";
	}

	public static function buy(){
		return new Axle();
		}
}

Then all you'd need to do is buy an Axle and you can attach Wheels or set it turning.

$axle = Axle::buy();
echo "{$axle->attachWheels()}<br>";
echo "{$axle->turn()}<br>";

And there you have it. If you like my idea of pattern allegories, please speak up in the comments. It will encourage me to do more. If you don't, then you're a philistine.

I originally thought I was going to have to do a lot of complicated gymnastics, mostly because I hadn't created a SOAP client or server before (I'd mostly done RESTful interfaces that used CURL or file_get_contents() to a URL). But I found out two things:

1. The WSDL (Web Services Description Language) and the server address weren't tied together. I could leave the WSDL address the same, but set up a simple flag in the SOAP client initiation routine to specify a different server when the system was in maintenance mode.
2. It's really quite simple to set up a SOAP server with the PHP SOAP extensions. It's literally just three lines of code (four, if you want to enable the WSDL cache).

Now, you combine that with Friday's post about the __call() magic method and you've got the makings of your SOAP simulator.

class CallCatcher {

	public function __call($method,$args){
		//code to store the method and args
		//to a database		
	}
}

$server = new SoapServer("http://www.example.com/api/api.wsdl");
$server->setClass("CallCatcher");
$server->handle();

You can now redirect your SOAP client to hit that service with all its requests instead of the normal server.

There are a selection of function names in OOP PHP called called magic methods. I'm no expert in them and only know about a third, but I'll do my best to describe what they do and how they work in a nutshell.

They are probably best described as event placeholders. Your classes will work without them. Your objects will instantiate without them. But if you want to make sure your class/object does something specific when a specific event occurs, you set up a function using the name reserved for magic method that corresponds to that event.

For example, the most famous magic method is __construct. When you instantiate an object based on a class, any code you want to run at instantiation is in there. A little less famous is __call. This is the method that gets invoked whenever you try to call a method that isn't in your class.

This is great if you're setting up an API and you want to have a handler for misnamed calls or some other error handling when a call doesn't correspond to an existing method. It's also great for when you want to... wait for it... fake a SOAP API without replicating all of its methods.

One of the elements of my SOAP capturing fake-out is that my SOAP impostor has ONE primary method...

class soapImpostor{

   public function __call($method,$args){
       // code to save the info in
       // $method and $args for later use
   }
}

I'll go into how the SOAP Impostor is built on Monday. But for now, I'm a little enamored with __call, and wanted to share.

Some early research on short circuiting a SOAP client and intercepting its calls was no help. Second thought was doing something like this to the API broker class's 16 methods.

if($maintenance_mode) {
   [store the call}
  } else {
   [do the call as normal]
 }

But it hit me while watching TV with my wife tonight (yay, "Royal Pains" is back) that my problem starts when the SOAP client is istantiated for handling the requests, so what if I used the regular SOAP client for every day activities, but created my own for when maintenance mode is on.

So the question for me to investigate at work is whether I want to simply create a class that will simulate a SOAP object, or essentially build an API to my storage interface, build my own WSDL for it, and then just substitute my WSDL for the normal one when the maintenance flag is turned on. What's it gonna be?

That is my experimentation at work tomorrow, when I'm not busy fielding the latest batch of design tweaks for newsletter templates that shall remain nameless.

I have a big refactoring project at work I'll talk about tomorrow.

What I'll leave with is this... PHP is the first girlfriend for many of us, but we programmers are a fickle lot. We either try to keep a girlfriend on the side or want to move onto the new sexy. What's the language that you can't stop checking out? For me it's JavaScript game engines and frameworks.