From 059ff45e365928ee90b43f6ae033b1de09d3118e Mon Sep 17 00:00:00 2001
From: Robert Reinhard <robert.reinhard@bkwld.com>
Date: Fri, 23 Aug 2013 11:46:31 -0700
Subject: [PATCH] Adding a chainable property that will randomly return NULL

---
 readme.md                        | 10 ++++++++++
 src/Faker/NullGenerator.php      | 22 ++++++++++++++++++++++
 src/Faker/Provider/Base.php      | 10 ++++++++++
 test/Faker/Provider/BaseTest.php | 12 ++++++++++++
 4 files changed, 54 insertions(+)
 create mode 100644 src/Faker/NullGenerator.php

diff --git a/readme.md b/readme.md
index 24d820b0..6df840d3 100644
--- a/readme.md
+++ b/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).
diff --git a/src/Faker/NullGenerator.php b/src/Faker/NullGenerator.php
new file mode 100644
index 00000000..8c2359b5
--- /dev/null
+++ b/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;
+    }
+  
+}
\ No newline at end of file
diff --git a/src/Faker/Provider/Base.php b/src/Faker/Provider/Base.php
index 6f51e04f..ffb2f3db 100644
--- a/src/Faker/Provider/Base.php
+++ b/src/Faker/Provider/Base.php
@@ -188,4 +188,14 @@ 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 mt_rand() / mt_getrandmax() <= $weight ? $this->generator : new \Faker\NullGenerator;
+    }
 }
diff --git a/test/Faker/Provider/BaseTest.php b/test/Faker/Provider/BaseTest.php
index 60aff679..19de22f8 100644
--- a/test/Faker/Provider/BaseTest.php
+++ b/test/Faker/Provider/BaseTest.php
@@ -130,4 +130,16 @@ 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));
+    }
 }