ValueObject > Human > represents a human

CHANGELOG.md

@@ -5,6 +5,7 @@ Common and useful classes, methods, exceptions etc.
 # 0.1.6
 
 1. Arrays > refactoring & more tests
+2. ValueObject > Human > represents a human
 
 # 0.1.5
 

docs/Value-Objects.md

@@ -137,6 +137,46 @@ $company = new Company(
 $asString = (string)$company; // "Test 1, 4th Avenue 10/200, 00123, New York, Bank 1, 12345"
 ```
 
+### Human
+
+##### Namespace
+
+`Meritoo\Common\ValueObject\Human`
+
+##### Info
+
+Represents human. Based on `\Meritoo\Common\Traits\ValueObject\HumanTrait` trait. Contains properties same as `HumanTrait` trait:
+1. `$firstName` - first name
+2. `$lastName` - last name
+3. `$email` - email address
+4. `$birthDate` - birth date
+
+##### New instance
+
+New instance can be created using constructor:
+
+```php
+new Human('John', 'Scott', 'john@scott.com', new \DateTime('2001-01-01'));
+```
+
+##### Methods
+
+Has getters for each property, e.g. `getFirstName()`, `getEmail()` etc.
+
+##### Conversion to string (the `__toString()` method)
+
+Instance of `Human` may be represented as string that contains first name, last name and email address (if provided).
+
+Example:
+
+```php
+$human1 = new Human('John', 'Scott');
+$asString1 = (string)$human1; // "John Scott"
+
+$human2 = new Human('John', 'Scott', 'john@scott.com', new \DateTime('2001-01-01'));
+$asString2 = (string)$human2; // "John Scott <john@scott.com>"
+```
+
 ### Version
 
 ##### Namespace

src/Traits/ValueObject/HumanTrait.php

@@ -0,0 +1,137 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits\ValueObject;
+
+/**
+ * Methods and properties related to human
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait HumanTrait
+{
+    /**
+     * First name
+     *
+     * @var string
+     */
+    protected $firstName;
+
+    /**
+     * Last name
+     *
+     * @var string
+     */
+    protected $lastName;
+
+    /**
+     * Email address
+     *
+     * @var string
+     */
+    protected $email;
+
+    /**
+     * Birth date
+     *
+     * @var \DateTime
+     */
+    protected $birthDate;
+
+    /**
+     * Class constructor
+     *
+     * @param string    $firstName First name
+     * @param string    $lastName  Last name
+     * @param string    $email     (optional) Email address
+     * @param \DateTime $birthDate (optional) Birth date
+     */
+    public function __construct($firstName, $lastName, $email = null, \DateTime $birthDate = null)
+    {
+        $this->firstName = $firstName;
+        $this->lastName = $lastName;
+        $this->email = $email;
+        $this->birthDate = $birthDate;
+    }
+
+    /**
+     * Returns representation of object as string
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        $template = '%s';
+
+        if ('' !== $this->email && null !== $this->email) {
+            $template .= ' <%s>';
+        }
+
+        return sprintf($template, $this->getFullName(), $this->email);
+    }
+
+    /**
+     * Returns first name
+     *
+     * @return string
+     */
+    public function getFirstName()
+    {
+        return $this->firstName;
+    }
+
+    /**
+     * Returns last name
+     *
+     * @return string
+     */
+    public function getLastName()
+    {
+        return $this->lastName;
+    }
+
+    /**
+     * Returns email address
+     *
+     * @return string|null
+     */
+    public function getEmail()
+    {
+        return $this->email;
+    }
+
+    /**
+     * Returns birth date
+     *
+     * @return \DateTime|null
+     */
+    public function getBirthDate()
+    {
+        return $this->birthDate;
+    }
+
+    /**
+     * Returns the full name
+     *
+     * @param bool $firstNameFirst (optional) If is set to true, first name is the first part. Otherwise - last name.
+     * @return string
+     */
+    public function getFullName($firstNameFirst = true)
+    {
+        $beginning = $this->lastName;
+        $finish = $this->firstName;
+
+        if ($firstNameFirst) {
+            $beginning = $this->firstName;
+            $finish = $this->lastName;
+        }
+
+        return trim(sprintf('%s %s', $beginning, $finish));
+    }
+}

src/ValueObject/Human.php

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\ValueObject;
+
+use Meritoo\Common\Traits\ValueObject\HumanTrait;
+
+/**
+ * Human
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class Human
+{
+    use HumanTrait;
+}

tests/ValueObject/HumanTest.php

@@ -0,0 +1,116 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Test\ValueObject;
+
+use Meritoo\Common\Test\Base\BaseTestCase;
+use Meritoo\Common\Type\OopVisibilityType;
+use Meritoo\Common\ValueObject\Human;
+
+/**
+ * Test case for the human
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class HumanTest extends BaseTestCase
+{
+    public function testConstructor()
+    {
+        static::assertConstructorVisibilityAndArguments(
+            Human::class,
+            OopVisibilityType::IS_PUBLIC,
+            4,
+            2
+        );
+    }
+
+    /**
+     * @param string $description Description of test
+     * @param Human  $human       Human to verify
+     * @param string $expected    Expected string
+     *
+     * @dataProvider provideHuman
+     */
+    public function testToString($description, Human $human, $expected)
+    {
+        static::assertSame($expected, (string)$human, $description);
+    }
+
+    public function testGetFirstName()
+    {
+        $empty = new Human('', '');
+        static::assertSame('', $empty->getFirstName());
+
+        $human = new Human('John', 'Scott');
+        static::assertSame('John', $human->getFirstName());
+    }
+
+    public function testGetLastName()
+    {
+        $empty = new Human('', '');
+        static::assertSame('', $empty->getLastName());
+
+        $human = new Human('John', 'Scott');
+        static::assertSame('Scott', $human->getLastName());
+    }
+
+    public function testGetBirthDate()
+    {
+        $empty = new Human('', '');
+        static::assertNull($empty->getBirthDate());
+
+        $human = new Human('John', 'Scott', '', new \DateTime('2001-01-01'));
+        static::assertEquals(new \DateTime('2001-01-01'), $human->getBirthDate());
+    }
+
+    public function testGetFullName()
+    {
+        $empty = new Human('', '');
+        static::assertSame('', $empty->getFullName());
+
+        $human = new Human('John', 'Scott', '', new \DateTime('2001-01-01'));
+        static::assertSame('John Scott', $human->getFullName());
+    }
+
+    public function testGetEmail()
+    {
+        $empty = new Human('', '');
+        static::assertNull($empty->getEmail());
+
+        $human = new Human('John', 'Scott', 'john@scott.com');
+        static::assertSame('john@scott.com', $human->getEmail());
+    }
+
+    public function provideHuman()
+    {
+        yield[
+            'Without any data (an empty human)',
+            new Human('', ''),
+            '',
+        ];
+
+        yield[
+            'With first and last name only',
+            new Human('John', 'Scott'),
+            'John Scott',
+        ];
+
+        yield[
+            'With first name, last name and email',
+            new Human('John', 'Scott', 'john@scott.com'),
+            'John Scott <john@scott.com>',
+        ];
+
+        yield[
+            'With whole/complete data',
+            new Human('John', 'Scott', 'john@scott.com', new \DateTime('2001-01-01')),
+            'John Scott <john@scott.com>',
+        ];
+    }
+}