Merge pull request #1266 from zachflower/feature/en_us_ssn

Add compliant en_US SSN generator

readme.md

@@ -935,6 +935,15 @@ echo $faker->bankAccountNumber;  // '51915734310'
 echo $faker->bankRoutingNumber;  // '212240302'
 ```
 
+### `Faker\Provider\en_US\Person`
+
+```php
+<?php
+
+// Generates a random Social Security Number
+echo $faker->ssn; // '123-45-6789'
+```
+
 ### `Faker\Provider\en_ZA\Company`
 
 ```php

src/Faker/Provider/en_US/Person.php

@@ -116,4 +116,16 @@ public static function suffix()
     {
         return static::randomElement(static::$suffix);
     }
+
+    /**
+     * @example '123-45-6789'
+     */
+    public static function ssn()
+    {
+        $area = mt_rand(0, 1) ? static::numberBetween(1, 665) : static::numberBetween(667, 899);
+        $group = static::numberBetween(1, 99);
+        $serial = static::numberBetween(1, 9999);
+
+        return sprintf("%03d-%02d-%04d", $area, $group, $serial);
+    }
 }

test/Faker/Provider/en_US/PersonTest.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Faker\Test\Provider\en_US;
+
+use Faker\Provider\en_US\Person;
+use Faker\Generator;
+
+class PersonTest extends \PHPUnit_Framework_TestCase
+{
+
+    /**
+     * @var Generator
+     */
+    private $faker;
+
+    public function setUp()
+    {
+        $faker = new Generator();
+        $faker->addProvider(new Person($faker));
+        $this->faker = $faker;
+    }
+
+    public function testSsn()
+    {
+        for ($i = 0; $i < 100; $i++) {
+            $number = $this->faker->ssn;
+
+            // should be in the format ###-##-####
+            $this->assertRegExp('/^[0-9]{3}-[0-9]{2}-[0-9]{4}$/', $number);
+
+            $parts = explode("-", $number);
+
+            // first part must be between 001 and 899, excluding 666
+            $this->assertNotEquals(666, $parts[0]);
+            $this->assertGreaterThan(0, $parts[0]);
+            $this->assertLessThan(900, $parts[0]);
+
+            // second part must be between 01 and 99
+            $this->assertGreaterThan(0, $parts[1]);
+            $this->assertLessThan(100, $parts[1]);
+
+            // the third part must be between 0001 and 9999
+            $this->assertGreaterThan(0, $parts[2]);
+            $this->assertLessThan(10000, $parts[2]);
+        }
+    }
+}