From 385fd5494628948de9aaaf35c90fb63c257ed43e Mon Sep 17 00:00:00 2001
From: Zachary Flower <zach@zacharyflower.com>
Date: Tue, 8 Aug 2017 16:00:45 -0600
Subject: [PATCH 1/3] Add compliant en_US SSN generator

---
 readme.md                                |  1 +
 src/Faker/Generator.php                  |  1 +
 src/Faker/Provider/en_US/Person.php      | 12 ++++++
 test/Faker/Provider/en_US/PersonTest.php | 47 ++++++++++++++++++++++++
 4 files changed, 61 insertions(+)
 create mode 100644 test/Faker/Provider/en_US/PersonTest.php

diff --git a/readme.md b/readme.md
index a297ca0602..d568acced0 100644
--- a/readme.md
+++ b/readme.md
@@ -140,6 +140,7 @@ Each of the generator properties (like `name`, `address`, and `lorem`) are calle
     firstNameMale                             // 'Maynard'
     firstNameFemale                           // 'Rachel'
     lastName                                  // 'Zulauf'
+    ssn                                       // '123-45-6789'
 
 ### `Faker\Provider\en_US\Address`
 
diff --git a/src/Faker/Generator.php b/src/Faker/Generator.php
index 0115870438..69470db52a 100644
--- a/src/Faker/Generator.php
+++ b/src/Faker/Generator.php
@@ -14,6 +14,7 @@
  * @method string title(string $gender = null)
  * @property string $titleMale
  * @property string $titleFemale
+ * @property string $ssn
  *
  * @property string $citySuffix
  * @property string $streetSuffix
diff --git a/src/Faker/Provider/en_US/Person.php b/src/Faker/Provider/en_US/Person.php
index 580f20b8e6..edfd63513d 100644
--- a/src/Faker/Provider/en_US/Person.php
+++ b/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);
+    }
 }
diff --git a/test/Faker/Provider/en_US/PersonTest.php b/test/Faker/Provider/en_US/PersonTest.php
new file mode 100644
index 0000000000..544a7b38e6
--- /dev/null
+++ b/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]);
+        }
+    }
+}

From f4c4cda99261eb2da42267eb4798261ea672e5bb Mon Sep 17 00:00:00 2001
From: Zachary Flower <zach@zacharyflower.com>
Date: Wed, 9 Aug 2017 08:17:39 -0600
Subject: [PATCH 2/3] Remove `ssn` property from Generator

---
 src/Faker/Generator.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/Faker/Generator.php b/src/Faker/Generator.php
index 69470db52a..0115870438 100644
--- a/src/Faker/Generator.php
+++ b/src/Faker/Generator.php
@@ -14,7 +14,6 @@
  * @method string title(string $gender = null)
  * @property string $titleMale
  * @property string $titleFemale
- * @property string $ssn
  *
  * @property string $citySuffix
  * @property string $streetSuffix

From aaf4772696312620ed87b41947ae4bb4eeb37dcc Mon Sep 17 00:00:00 2001
From: Zachary Flower <zach@zacharyflower.com>
Date: Wed, 9 Aug 2017 08:27:55 -0600
Subject: [PATCH 3/3] Move `ssn` to separate `Faker\Provider\en_US\Person`
 group underneath the `Language specific formatters` section

---
 readme.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index d568acced0..6e75ce771b 100644
--- a/readme.md
+++ b/readme.md
@@ -140,7 +140,6 @@ Each of the generator properties (like `name`, `address`, and `lorem`) are calle
     firstNameMale                             // 'Maynard'
     firstNameFemale                           // 'Rachel'
     lastName                                  // 'Zulauf'
-    ssn                                       // '123-45-6789'
 
 ### `Faker\Provider\en_US\Address`
 
@@ -936,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