Merge pull request #166 from weotch/optional-data

Adding a chainable property that will randomly return NULL

readme.md

@@ -195,6 +195,16 @@ Each of the generator properties (like `name`, `address`, and `lorem`) are calle
     safeColorName          // 'fuchsia'
     colorName              // 'Gainsbor'
 
+## Optional data
+
+All formatters can be made optional by chaining `optional`. When optional, the formatter will randomly return `NULL`, which can be useful for seeding non-required fields. For example:
+
+    $faker->optional->country
+    
+You can skew the randomization towards more nulls or less by passing an argument to `optional()`.  At 0, *only* `NULL` is returned.  At 1, it is never returned.
+
+    $faker->optional(.75)->country
+
 ## Localization
 
 `Faker\Factory` can take a locale as an argument, to return localized data. If no localized provider is found, the factory fallbacks to the default locale (en_EN).

src/Faker/NullGenerator.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Faker;
+
+/**
+ * This generator returns NULL for all called propertis.  It works with
+ * Faker\Generator\Base->optional()
+ */
+class NullGenerator
+{
+  
+    public function __get($attribute) 
+    {
+        return null;
+    }
+
+    public function __call($method, $attributes)
+    {
+        return null;
+    }
+  
+}

src/Faker/Provider/Base.php

@@ -188,4 +188,19 @@ class Base
     {
         return extension_loaded('mbstring') ? mb_strtoupper($string, 'UTF-8') : strtoupper($string);
     }
+    
+    /**
+     * Chainable method for making any formatter optional
+     * @param float $weight Set the percentage that the formatter is empty. "0" would always return null,
+     * "1" would always return the formatter
+     * @return null or whatever the formatter would use
+     */
+    public function optional($weight = 0.5)
+    {
+        // Return the formatter
+        if (mt_rand() / mt_getrandmax() <= $weight) return $this->generator;
+        
+        // Return NULL
+        else return new \Faker\NullGenerator();
+    }
 }

test/Faker/Provider/BaseTest.php

@@ -130,4 +130,18 @@ class BaseTest extends \PHPUnit_Framework_TestCase
     {
         $this->assertRegExp('/foo[a-z]Ba\dr/', BaseProvider::bothify('foo?Ba#r'));
     }
+    
+    public function testOptionalChainingOfProperty()
+    {
+        $faker = \Faker\Factory::create();
+        $this->assertNotNull($faker->optional(1)->randomNumber);
+        $this->assertNull($faker->optional(0)->randomNumber);
+    }
+    
+    public function testOptionalChainingOfMethod()
+    {
+        $faker = \Faker\Factory::create();
+        $this->assertNotNull($faker->optional(1)->randomNumber(4));
+        $this->assertNull($faker->optional(0)->randomNumber(4));
+    }
 }