better documentation

README.markdown

@@ -18,8 +18,16 @@ and any options provided to be overwritten or deleted.
 
 ## Creating Fixtures
 
-Fixtures for **Post Fixtures** are written in JSON. Save them with the theme/plugin you're developing and
+Fixtures for **Post Fixtures** are written in either JSON or PHP.
-copy/paste them into **Post Fixtures** when you need to test specific features.
+
+### JSON
+
+JSON fixtures can be saved anywhere with the theme/plugin you're developing and then copied and pasted into **Post Fixtures** when you need to test specific features.
+
+### PHP
+
+PHP fixtures are saved in a directory within your theme or plugin called `fixtures` with the extension `.inc`.
+See the example fixture under `fixtures/php-ficture.inc` as well as the example below.
 
 ### What's Supported?
 
@@ -29,6 +37,7 @@ As of the current release on GitHub, the following WordPress features are suppor
 	* Most post data found in the `posts` table
 	* Post metadata with serialization
 * Categories
+* Tags
 * Blog options with serialization and deletion
 
 ## Contributing
@@ -58,7 +67,7 @@ create a new Issue.
 					]
 				}
 			},
-			"tags": "tag 1,tag2"
+			"tags": "tag 1,tag 2"
 		},
 		{
 			"post_date": "2010-01-01 10:00am",
@@ -79,3 +88,29 @@ create a new Issue.
 
 ### PHP
 
+<pre>
+// build an object immediately, and get the new post's ID
+$post_id = $builder->post('This is a sample post')
+                   ->date('2010-01-01 9:00am')
+                   ->content("This is the post's content")
+                   ->categories("Top Level 1/Sub Category 1,Top Level 2/Sub Category 2")
+                   ->metadata('field-1', 'value-1')
+                   ->metadata('field-2', array(
+                       'a_complex' => 'field',
+                       'with' => array(
+                       	'lots', 'of', 'nested', 'datatypes'
+                       )
+                     ))
+                   ->tags('tag 1,tag 2')->build();
+
+// build and object at the end, if order doesn't matter
+$builder->post('This is the second sample post')
+        ->date('2010-01-01 10:00am')
+        ->content("This is the second post's content")
+        ->categories("Top Level 1/Sub Category 2,Top Level 2/Sub Category 2")->defer();
+
+// convenience wrapper around options setting
+$builder->option('an-option-to-set', 'simple-string')
+        ->option('an-option-to-serialize', array('this' => 'is a hash'))
+        ->option('an-option-to-delete', false);
+</pre>