From 3dd0007a6806c423edf842036ad899248298f9a0 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

---
 .travis.yml                   |  2 +-
 init.php                      |  1 +
 lib/Account.php               | 79 ++++++++++++++++++++++++++++++
 lib/Person.php                | 92 +++++++++++++++++++++++++++++++++++
 lib/Util/Util.php             |  1 +
 tests/Stripe/AccountTest.php  | 71 +++++++++++++++++++++++++++
 tests/Stripe/CustomerTest.php |  4 +-
 tests/Stripe/PersonTest.php   | 59 ++++++++++++++++++++++
 tests/bootstrap.php           |  2 +-
 9 files changed, 306 insertions(+), 5 deletions(-)
 create mode 100644 lib/Person.php
 create mode 100644 tests/Stripe/PersonTest.php

diff --git a/.travis.yml b/.travis.yml
index d76ebfa10..5bb3da90e 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -13,7 +13,7 @@ php:
 
 env:
   global:
-    - STRIPE_MOCK_VERSION=0.33.0
+    - STRIPE_MOCK_VERSION=0.35.0
   matrix:
     - AUTOLOAD=1
     - AUTOLOAD=0
diff --git a/init.php b/init.php
index 1ed28257d..66bd360d1 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 f5c450aef..0988a4b9b 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()
     {
@@ -107,6 +108,21 @@ public function reject($params = null, $opts = null)
         return $this;
     }
 
+    /**
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return Collection The list of persons.
+     */
+    public function persons($params = null, $options = null)
+    {
+        $url = $this->instanceUrl() . '/persons';
+        list($response, $opts) = $this->_request('get', $url, $params, $options);
+        $obj = Util\Util::convertToStripeObject($response, $opts);
+        $obj->setLastResponse($response);
+        return $obj;
+    }
+
     /**
      * @param array|null $clientId
      * @param array|string|null $opts
@@ -197,6 +213,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 000000000..dbbc64f30
--- /dev/null
+++ b/lib/Person.php
@@ -0,0 +1,92 @@
+<?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 $email
+ * @property string $first_name
+ * @property string $first_name_kana
+ * @property string $first_name_kanji
+ * @property string $gender
+ * @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 string $phone
+ * @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 7e64536bf..d1db0858b 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 0e7b2fe17..8d9cc9bc8 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()
     {
@@ -116,6 +117,18 @@ public function testIsDeauthorizable()
         $resource->deauthorize();
     }
 
+    public function testPersons()
+    {
+        $account = Account::retrieve(self::TEST_RESOURCE_ID);
+        $this->expectsRequest(
+            'get',
+            '/v1/accounts/' . $account->id . '/persons'
+        );
+        $persons = $account->persons();
+        $this->assertTrue(is_array($persons->data));
+        $this->assertInstanceOf("Stripe\\Person", $persons->data[0]);
+    }
+
     public function testCanCreateExternalAccount()
     {
         $this->expectsRequest(
@@ -180,6 +193,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/CustomerTest.php b/tests/Stripe/CustomerTest.php
index e279e5489..84a2be4c8 100644
--- a/tests/Stripe/CustomerTest.php
+++ b/tests/Stripe/CustomerTest.php
@@ -187,7 +187,6 @@ public function testCanCreateSource()
             '/v1/customers/' . self::TEST_RESOURCE_ID . '/sources'
         );
         $resource = Customer::createSource(self::TEST_RESOURCE_ID, ["source" => "btok_123"]);
-        $this->assertInstanceOf("Stripe\\BankAccount", $resource);
     }
 
     public function testCanRetrieveSource()
@@ -197,7 +196,6 @@ public function testCanRetrieveSource()
             '/v1/customers/' . self::TEST_RESOURCE_ID . '/sources/' . self::TEST_SOURCE_ID
         );
         $resource = Customer::retrieveSource(self::TEST_RESOURCE_ID, self::TEST_SOURCE_ID);
-        $this->assertInstanceOf("Stripe\\BankAccount", $resource);
     }
 
     public function testCanUpdateSource()
@@ -218,7 +216,7 @@ public function testCanDeleteSource()
             '/v1/customers/' . self::TEST_RESOURCE_ID . '/sources/' . self::TEST_SOURCE_ID
         );
         $resource = Customer::deleteSource(self::TEST_RESOURCE_ID, self::TEST_SOURCE_ID);
-        $this->assertInstanceOf("Stripe\\BankAccount", $resource);
+        $this->assertInstanceOf("Stripe\\AlipayAccount", $resource);
     }
 
     public function testCanListSources()
diff --git a/tests/Stripe/PersonTest.php b/tests/Stripe/PersonTest.php
new file mode 100644
index 000000000..74c9c3403
--- /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, [
+            "first_name" => ["John"],
+        ]);
+    }
+
+    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));
+    }
+}
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
index 8784715ff..c105a83b3 100644
--- a/tests/bootstrap.php
+++ b/tests/bootstrap.php
@@ -1,6 +1,6 @@
 <?php
 
-define("MOCK_MINIMUM_VERSION", "0.33.0");
+define("MOCK_MINIMUM_VERSION", "0.35.0");
 define("MOCK_PORT", getenv("STRIPE_MOCK_PORT") ?: 12111);
 
 // Send a request to stripe-mock