Implementing new Birthday class to handle Graph API response variations

docs/Birthday.fbmd

@@ -0,0 +1,63 @@
+<card>
+# Birthday for the Facebook SDK for PHP
+
+Extends `\DateTime` and represents a user's birthday returned from the Graph API which can be returned omitting certain information.
+
+Users may opt not to share birth day or month, or may not share birth year. Possible returns:
+
+* MM/DD/YYYY
+* MM/DD
+* YYYY
+</card>
+
+<card>
+## Facebook\GraphNodes\Birthday {#overview}
+
+After retrieving a GraphUser from the Graph API, the `getBirthday()` method will return the birthday in the form of a `Facebook\GraphNodes\Birthday` entity which indicates which aspects of the birthday the user opted to share.
+
+The `Facebook\GraphNodes\Birthday` entity extends `DateTime` so `format` may be used to present the information appropriately depending on what information it contains.
+
+Usage:
+
+~~~~
+$fb = new Facebook\Facebook(\* *\);
+// Returns a `Facebook\FacebookResponse` object
+$response = $fb->get('/me');
+
+// Get the response typed as a GraphUser
+$user = $response->getGraphUser();
+
+// Gets birthday value, assume Graph return was format MM/DD
+$birthday = $user->getBirthday();
+
+var_dump($birthday);
+// class Facebook\GraphNodes\Birthday ...
+
+var_dump($birthday->hasDate());
+// true
+
+var_dump($birthday->hasYear());
+// false
+
+var_dump($birthday->format('m/d'));
+// 03/21
+~~~~
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### hasDate() {#has-date}
+~~~~
+public boolean hasDate()
+~~~~
+Returns whether or not the birthday object contains the day and month of birth.
+</card>
+
+<card>
+### hasYear() {#has-year}
+~~~~
+public boolean hasYear()
+~~~~
+Returns whether or not the birthday object contains the year of birth.
+</card>

docs/GraphNode.fbmd

@@ -166,9 +166,9 @@ Returns the `link` property for the user as a string if present.
 
 ### getBirthday() {#user-getbirthday}
 ~~~~
-public \DateTime|null getBirthday()
+public \Facebook\GraphNodes\Birthday|null getBirthday()
 ~~~~
-Returns the `birthday` property for the user as a `\DateTime` if present.
+Returns the `birthday` property for the user as a [`Facebook\GraphNodes\Birthday`](/docs/php/Birthday) if present.
 
 ### getLocation() {#user-getlocation}
 ~~~~

src/Facebook/GraphNodes/Birthday.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * Copyright 2016 Facebook, Inc.
+ *
+ * You are hereby granted a non-exclusive, worldwide, royalty-free license to
+ * use, copy, modify, and distribute this software in source code or binary
+ * form for use in connection with the web services and APIs provided by
+ * Facebook.
+ *
+ * As with any software that integrates with the Facebook platform, your use
+ * of this software is subject to the Facebook Developer Principles and
+ * Policies [http://developers.facebook.com/policy/]. This copyright notice
+ * shall be included in all copies or substantial portions of the software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ *
+ */
+namespace Facebook\GraphNodes;
+
+use DateTime;
+
+/**
+ * Birthday object to handle various Graph return formats
+ *
+ * @package Facebook
+ */
+class Birthday extends DateTime
+{
+    /**
+     * @var bool
+     */
+    private $hasDate = false;
+
+    /**
+     * @var bool
+     */
+    private $hasYear = false;
+
+    /**
+     * Parses Graph birthday format to set indication flags, possible values:
+     *
+     *  MM/DD/YYYY
+     *  MM/DD
+     *  YYYY
+     *
+     * @link https://developers.facebook.com/docs/graph-api/reference/user
+     *
+     * @param string $date
+     */
+    public function __construct($date)
+    {
+        $parts = explode('/', $date);
+
+        $this->hasYear = count($parts) === 3 || count($parts) === 1;
+        $this->hasDate = count($parts) === 3 || count($parts) === 2;
+
+        parent::__construct($date);
+    }
+
+    /**
+     * Returns whether date object contains birth day and month
+     *
+     * @return bool
+     */
+    public function hasDate()
+    {
+        return $this->hasDate;
+    }
+
+    /**
+     * Returns whether date object contains birth year
+     *
+     * @return bool
+     */
+    public function hasYear()
+    {
+        return $this->hasYear;
+    }
+}

src/Facebook/GraphNodes/GraphNode.php

@@ -62,10 +62,11 @@ public function castItems(array $data)
         foreach ($data as $k => $v) {
             if ($this->shouldCastAsDateTime($k)
                 && (is_numeric($v)
-                    || $k === 'birthday'
                     || $this->isIso8601DateString($v))
             ) {
                 $items[$k] = $this->castToDateTime($v);
+            } elseif ($k === 'birthday') {
+                $items[$k] = $this->castToBirthday($v);
             } else {
                 $items[$k] = $v;
             }
@@ -149,7 +150,6 @@ public function shouldCastAsDateTime($key)
             'backdated_time',
             'issued_at',
             'expires_at',
-            'birthday',
             'publish_time'
         ], true);
     }
@@ -173,6 +173,18 @@ public function castToDateTime($value)
         return $dt;
     }
 
+    /**
+     * Casts a birthday value from Graph to Birthday
+     *
+     * @param string $value
+     *
+     * @return Birthday
+     */
+    public function castToBirthday($value)
+    {
+        return new Birthday($value);
+    }
+
     /**
      * Getter for $graphObjectMap.
      *

tests/GraphNodes/GraphUserTest.php

@@ -42,7 +42,25 @@ public function setUp()
     public function testDatesGetCastToDateTime()
     {
         $dataFromGraph = [
-            'birthday' => '1984-01-01',
+            'updated_time' => '2016-04-26 13:22:05',
+        ];
+
+        $this->responseMock
+            ->shouldReceive('getDecodedBody')
+            ->once()
+            ->andReturn($dataFromGraph);
+        $factory = new GraphNodeFactory($this->responseMock);
+        $graphNode = $factory->makeGraphUser();
+
+        $updatedTime = $graphNode->getField('updated_time');
+
+        $this->assertInstanceOf('DateTime', $updatedTime);
+    }
+
+    public function testBirthdaysGetCastToBirthday()
+    {
+        $dataFromGraph = [
+            'birthday' => '1984/01/01',
         ];
 
         $this->responseMock
@@ -54,7 +72,53 @@ public function testDatesGetCastToDateTime()
 
         $birthday = $graphNode->getBirthday();
 
+        // Test to ensure BC
         $this->assertInstanceOf('DateTime', $birthday);
+
+        $this->assertInstanceOf('\\Facebook\\GraphNodes\\Birthday', $birthday);
+        $this->assertTrue($birthday->hasDate());
+        $this->assertTrue($birthday->hasYear());
+        $this->assertEquals('1984/01/01', $birthday->format('Y/m/d'));
+    }
+
+    public function testBirthdayCastHandlesDateWithoutYear()
+    {
+        $dataFromGraph = [
+            'birthday' => '03/21',
+        ];
+
+        $this->responseMock
+            ->shouldReceive('getDecodedBody')
+            ->once()
+            ->andReturn($dataFromGraph);
+        $factory = new GraphNodeFactory($this->responseMock);
+        $graphNode = $factory->makeGraphUser();
+
+        $birthday = $graphNode->getBirthday();
+
+        $this->assertTrue($birthday->hasDate());
+        $this->assertFalse($birthday->hasYear());
+        $this->assertEquals('03/21', $birthday->format('m/d'));
+    }
+
+    public function testBirthdayCastHandlesYearWithoutDate()
+    {
+        $dataFromGraph = [
+            'birthday' => '1984',
+        ];
+
+        $this->responseMock
+            ->shouldReceive('getDecodedBody')
+            ->once()
+            ->andReturn($dataFromGraph);
+        $factory = new GraphNodeFactory($this->responseMock);
+        $graphNode = $factory->makeGraphUser();
+
+        $birthday = $graphNode->getBirthday();
+
+        $this->assertTrue($birthday->hasYear());
+        $this->assertFalse($birthday->hasDate());
+        $this->assertEquals('1984', $birthday->format('Y'));
     }
 
     public function testPagePropertiesWillGetCastAsGraphPageObjects()