From 635e03fe7f03f447fd653c3a4305f12df8de5596 Mon Sep 17 00:00:00 2001
From: Remi Jannel <remi@stripe.com>
Date: Fri, 12 Oct 2018 09:52:43 -0700
Subject: [PATCH] Add support for the Person resource

---
 init.php                     |  1 +
 lib/Account.php              | 64 +++++++++++++++++++++++++
 lib/Person.php               | 91 ++++++++++++++++++++++++++++++++++++
 lib/Util/Util.php            |  1 +
 tests/Stripe/AccountTest.php | 59 +++++++++++++++++++++++
 tests/Stripe/PersonTest.php  | 59 +++++++++++++++++++++++
 6 files changed, 275 insertions(+)
 create mode 100644 lib/Person.php
 create mode 100644 tests/Stripe/PersonTest.php

diff --git a/init.php b/init.php
index 1ed28257d3..66bd360d11 100644
--- a/init.php
+++ b/init.php
@@ -95,6 +95,7 @@
 require(dirname(__FILE__) . '/lib/OrderReturn.php');
 require(dirname(__FILE__) . '/lib/PaymentIntent.php');
 require(dirname(__FILE__) . '/lib/Payout.php');
+require(dirname(__FILE__) . '/lib/Person.php');
 require(dirname(__FILE__) . '/lib/Plan.php');
 require(dirname(__FILE__) . '/lib/Product.php');
 require(dirname(__FILE__) . '/lib/Recipient.php');
diff --git a/lib/Account.php b/lib/Account.php
index f5c450aef5..2a03e6eb70 100644
--- a/lib/Account.php
+++ b/lib/Account.php
@@ -67,6 +67,7 @@ public static function getSavedNestedResources()
 
     const PATH_EXTERNAL_ACCOUNTS = '/external_accounts';
     const PATH_LOGIN_LINKS = '/login_links';
+    const PATH_PERSONS = '/persons';
 
     public function instanceUrl()
     {
@@ -197,6 +198,69 @@ public static function createLoginLink($id, $params = null, $opts = null)
         return self::_createNestedResource($id, static::PATH_LOGIN_LINKS, $params, $opts);
     }
 
+    /**
+     * @param array|null $id The ID of the account on which to create the person.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Person
+     */
+    public static function createPerson($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_PERSONS, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the person belongs.
+     * @param array|null $personId The ID of the person to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Person
+     */
+    public static function retrievePerson($id, $personId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_PERSONS, $personId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the person belongs.
+     * @param array|null $personId The ID of the person to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Person
+     */
+    public static function updatePerson($id, $personId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_PERSONS, $personId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the person belongs.
+     * @param array|null $personId The ID of the person to delete.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Person
+     */
+    public static function deletePerson($id, $personId, $params = null, $opts = null)
+    {
+        return self::_deleteNestedResource($id, static::PATH_PERSONS, $personId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account on which to retrieve the persons.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Person
+     */
+    public static function allPersons($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_PERSONS, $params, $opts);
+    }
+
     public function serializeParameters($force = false)
     {
         $update = parent::serializeParameters($force);
diff --git a/lib/Person.php b/lib/Person.php
new file mode 100644
index 0000000000..b08193e865
--- /dev/null
+++ b/lib/Person.php
@@ -0,0 +1,91 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * Class Person
+ *
+ * @package Stripe
+ *
+ * @property string $id
+ * @property string $object
+ * @property string $account
+ * @property mixed $address
+ * @property mixed $address_kana
+ * @property mixed $address_kanji
+ * @property int $created
+ * @property bool $deleted
+ * @property mixed $dob
+ * @property string $first_name
+ * @property string $first_name_kana
+ * @property string $first_name_kanji
+ * @property string $gender
+ * @property string $id_number_country
+ * @property bool $id_number_provided
+ * @property string $last_name
+ * @property string $last_name_kana
+ * @property string $last_name_kanji
+ * @property string $maiden_name
+ * @property StripeObject $metadata
+ * @property mixed $relationship
+ * @property mixed $requirements
+ * @property bool $ssn_last_4_provided
+ * @property mixed $verification
+ */
+class Person extends ApiResource
+{
+    const OBJECT_NAME = "person";
+
+    use ApiOperations\Delete;
+    use ApiOperations\Update;
+
+    /**
+     * @return string The API URL for this Stripe account reversal.
+     */
+    public function instanceUrl()
+    {
+        $id = $this['id'];
+        $account = $this['account'];
+        if (!$id) {
+            throw new Error\InvalidRequest(
+                "Could not determine which URL to request: " .
+                "class instance has invalid ID: $id",
+                null
+            );
+        }
+        $id = Util\Util::utf8($id);
+        $account = Util\Util::utf8($account);
+
+        $base = Account::classUrl();
+        $accountExtn = urlencode($account);
+        $extn = urlencode($id);
+        return "$base/$accountExtn/persons/$extn";
+    }
+
+    /**
+     * @param array|string $_id
+     * @param array|string|null $_opts
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function retrieve($_id, $_opts = null)
+    {
+        $msg = "Persons cannot be accessed without an account ID. " .
+               "Retrieve a Person using \$account->retrievePerson('person_id') instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+
+    /**
+     * @param string $_id
+     * @param array|null $_params
+     * @param array|string|null $_options
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function update($_id, $_params = null, $_options = null)
+    {
+        $msg = "Persons cannot be accessed without an account ID. " .
+               "Retrieve a Person using \$account->retrievePerson('person_id') instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+}
diff --git a/lib/Util/Util.php b/lib/Util/Util.php
index 7e64536bf6..d1db0858b1 100644
--- a/lib/Util/Util.php
+++ b/lib/Util/Util.php
@@ -109,6 +109,7 @@ public static function convertToStripeObject($resp, $opts)
             \Stripe\OrderReturn::OBJECT_NAME => 'Stripe\\OrderReturn',
             \Stripe\PaymentIntent::OBJECT_NAME => 'Stripe\\PaymentIntent',
             \Stripe\Payout::OBJECT_NAME => 'Stripe\\Payout',
+            \Stripe\Person::OBJECT_NAME => 'Stripe\\Person',
             \Stripe\Plan::OBJECT_NAME => 'Stripe\\Plan',
             \Stripe\Product::OBJECT_NAME => 'Stripe\\Product',
             \Stripe\Recipient::OBJECT_NAME => 'Stripe\\Recipient',
diff --git a/tests/Stripe/AccountTest.php b/tests/Stripe/AccountTest.php
index 0e7b2fe17e..e0c23f7357 100644
--- a/tests/Stripe/AccountTest.php
+++ b/tests/Stripe/AccountTest.php
@@ -6,6 +6,7 @@ class AccountTest extends TestCase
 {
     const TEST_RESOURCE_ID = 'acct_123';
     const TEST_EXTERNALACCOUNT_ID = 'ba_123';
+    const TEST_PERSON_ID = 'person_123';
 
     public function testIsListable()
     {
@@ -180,6 +181,64 @@ public function testCanCreateLoginLink()
         $this->assertInstanceOf("Stripe\\LoginLink", $resource);
     }
 
+    public function testCanCreatePerson()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/persons'
+        );
+        $resource = Account::createPerson(self::TEST_RESOURCE_ID, [
+            "dob" => [
+                "day" => 1,
+                "month" => 1,
+                "year" => 1980
+            ]
+        ]);
+        $this->assertInstanceOf("Stripe\\Person", $resource);
+    }
+
+    public function testCanRetrievePerson()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/persons/' . self::TEST_PERSON_ID
+        );
+        $resource = Account::retrievePerson(self::TEST_RESOURCE_ID, self::TEST_PERSON_ID);
+        $this->assertInstanceOf("Stripe\\Person", $resource);
+    }
+
+    public function testCanUpdatePerson()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/persons/' . self::TEST_PERSON_ID
+        );
+        $resource = Account::updatePerson(self::TEST_RESOURCE_ID, self::TEST_PERSON_ID, [
+            "first_name" => "First name",
+        ]);
+        $this->assertInstanceOf("Stripe\\Person", $resource);
+    }
+
+    public function testCanDeletePerson()
+    {
+        $this->expectsRequest(
+            'delete',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/persons/' . self::TEST_PERSON_ID
+        );
+        $resource = Account::deletePerson(self::TEST_RESOURCE_ID, self::TEST_PERSON_ID);
+        $this->assertTrue($resource->deleted);
+    }
+
+    public function testCanListPersons()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/persons'
+        );
+        $resources = Account::allPersons(self::TEST_RESOURCE_ID);
+        $this->assertTrue(is_array($resources->data));
+    }
+
     public function testSerializeNewAdditionalOwners()
     {
         $obj = Util\Util::convertToStripeObject([
diff --git a/tests/Stripe/PersonTest.php b/tests/Stripe/PersonTest.php
new file mode 100644
index 0000000000..1cab8de2ec
--- /dev/null
+++ b/tests/Stripe/PersonTest.php
@@ -0,0 +1,59 @@
+<?php
+
+namespace Stripe;
+
+class PersonTest extends TestCase
+{
+    const TEST_ACCOUNT_ID = 'acct_123';
+    const TEST_RESOURCE_ID = 'person_123';
+
+    public function testHasCorrectUrl()
+    {
+        $resource = \Stripe\Account::retrievePerson(self::TEST_ACCOUNT_ID, self::TEST_RESOURCE_ID);
+        $this->assertSame(
+            "/v1/accounts/" . self::TEST_ACCOUNT_ID . "/persons/" . self::TEST_RESOURCE_ID,
+            $resource->instanceUrl()
+        );
+    }
+
+    /**
+     * @expectedException \Stripe\Error\InvalidRequest
+     */
+    public function testIsNotDirectlyRetrievable()
+    {
+        Person::retrieve(self::TEST_RESOURCE_ID);
+    }
+
+    public function testIsSaveable()
+    {
+        $resource = \Stripe\Account::retrievePerson(self::TEST_ACCOUNT_ID, self::TEST_RESOURCE_ID);
+        $resource->first_name = "value";
+        $this->expectsRequest(
+            'post',
+            '/v1/accounts/' . self::TEST_ACCOUNT_ID . '/persons/' . self::TEST_RESOURCE_ID
+        );
+        $resource->save();
+        $this->assertSame("Stripe\\Person", get_class($resource));
+    }
+
+    /**
+     * @expectedException \Stripe\Error\InvalidRequest
+     */
+    public function testIsNotDirectlyUpdatable()
+    {
+        Person::update(self::TEST_RESOURCE_ID, [
+            "metadata" => ["key" => "value"],
+        ]);
+    }
+
+    public function testIsDeletable()
+    {
+        $resource = \Stripe\Account::retrievePerson(self::TEST_ACCOUNT_ID, self::TEST_RESOURCE_ID);
+        $this->expectsRequest(
+            'delete',
+            '/v1/accounts/' . self::TEST_ACCOUNT_ID . '/persons/' . self::TEST_RESOURCE_ID
+        );
+        $resource->delete();
+        $this->assertSame("Stripe\\Person", get_class($resource));
+    }
+}