Merge pull request #1 from khepin/more-mutators

Additional Mutators

Author: elliotfehr

README.md

@@ -47,7 +47,7 @@ class User extends Model
      * {@inheritdoc}
      */
     protected $table = 'users';
-    
+
     /**
      * {@inheritdoc}
      */
@@ -59,11 +59,20 @@ class User extends Model
 
 This will automatically serialize/unserialize the `id` attribute on the `User` model when
 getting/setting the attribute from the database. This allows you to no longer need to set
-accessors/mutator methods on the model directly. 
+accessors/mutator methods on the model directly.
 
 > **Note:**  Unlike the built in Laravel accessors/mutators,
 this package will serialize the attribute values when they are passed to an Eloquent query builder.
 
+Included Mutators
+-----------------
+
+- `uuid_v1_binary` Will take a uuid version 1, re-order its bytes so that if uuidA was generated before uuidB, then storedUuidA < storedUuidB, and store it in the database as 16 bytes of data. For more information on the re-ordering of bytes, see: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/.
+- `ip_binary` Will take a string representation of an IPv4 or IPv6 and store it as 16 bytes in the database.
+- `encrypt_string` Will take a non encrypted string and encrypt it when going to the database.
+- `hex_binary` Will take any hexadecimal string attribute and store it as binary data.
+- `unix_timestamp` Will take a Carbon date but store it as an integer unix timestamp.
+
 Creating Custom Mutators
 ------------------------
 
@@ -74,7 +83,7 @@ To define a custom mutator, you'll need to create a class that implements
 any caching logic at the mutator level.
 
 When building and registering a Mutator, it is important to know that they
-are resolved automatically from the Laravel IOC container, which means you may create 
+are resolved automatically from the Laravel IOC container, which means you may create
 service providers for them if they require custom constructor arguments.
 
 ```php

config/config.php

@@ -8,5 +8,7 @@
         'uuid_v1_binary' => \Weebly\Mutate\Mutators\UuidV1BinaryMutator::class,
         'ip_binary'      => \Weebly\Mutate\Mutators\IpBinaryMutator::class,
         'encrypt_string' => \Weebly\Mutate\Mutators\EncryptStringMutator::class,
+        'hex_binary'     => \Weebly\Mutate\Mutators\HexBinaryMutator::class,
+        'unix_timestamp' => \Weebly\Mutate\Mutators\UnixTimestampMutator::class,
     ],
 ];

src/Mutators/HexBinaryMutator.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Weebly\Mutate\Mutators;
+
+use Weebly\Mutate\Exceptions\MutateException;
+
+/**
+ * Presents an attribute as a hexadecimal string.
+ * Stores the attribute as a byte array.
+ */
+class HexBinaryMutator implements MutatorContract
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function serializeAttribute($value)
+    {
+        if (! ctype_xdigit($value) || strlen($value) % 2 !== 0) {
+            throw new MutateException(__METHOD__.' expects the value to be serialized to be a hexadecimal string.');
+        }
+
+        return hex2bin($value);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function unserializeAttribute($value)
+    {
+        if (! $value) {
+            return;
+        }
+
+        return bin2hex($value);
+    }
+}

src/Mutators/UnixTimestampMutator.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Weebly\Mutate\Mutators;
+
+use Carbon\Carbon;
+use Weebly\Mutate\Exceptions\MutateException;
+
+/**
+ * Presents an attribute as Carbon date object (http://carbon.nesbot.com/)
+ * Stores the attribute as unix epoch timestamp.
+ */
+class UnixTimestampMutator implements MutatorContract
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function serializeAttribute($value)
+    {
+        if (! $value instanceof Carbon) {
+            throw new MutateException(__METHOD__." expects a Carbon\Carbon value. Received: ".print_r($value, true));
+        }
+
+        return $value->timestamp;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function unserializeAttribute($value)
+    {
+        if (! is_int($value) && ! ctype_digit($value)) {
+            return;
+        }
+
+        return Carbon::createFromTimestamp($value);
+    }
+}

tests/Integration/MutatorTest.php

@@ -50,6 +50,13 @@ public function setUp()
         });
 
         DB::connection()->getPdo()->exec('ALTER TABLE test_model ADD id BINARY(16);');
+
+        Schema::create('timestamped_model', function ($table) {
+            $table->increments('id');
+            $table->string('name');
+            $table->integer('created_at');
+            $table->integer('updated_at');
+        });
     }
 
     public function test_where()
@@ -117,6 +124,18 @@ public function test_pluck_with_key()
         $ids = TestModel::where('id', $id)->pluck('id', 'location')->toArray();
         $this->assertEquals([$location => $id], $ids);
     }
+
+    public function test_timestamps()
+    {
+        (new TimestampedModel())->create(['name' => 'Model']);
+        $model = TimestampedModel::first();
+        $this->assertInstanceOf('Carbon\Carbon', $model->created_at);
+        $this->assertInstanceOf('Carbon\Carbon', $model->updated_at);
+
+        $values = \DB::table('timestamped_model')->first();
+        $this->assertTrue(ctype_digit($values->created_at));
+        $this->assertTrue(ctype_digit($values->updated_at));
+    }
 }
 
 class TestModel extends Model
@@ -150,7 +169,19 @@ class TestModel extends Model
      * {@inheritdoc}
      */
     protected $mutate = [
-        'id'       => 'uuid_v1_binary',
+        'id' => 'uuid_v1_binary',
         'location' => 'encrypt_string',
     ];
 }
+
+class TimestampedModel extends Model
+{
+    protected $table = 'timestamped_model';
+
+    protected $guarded = [];
+
+    protected $mutate = [
+        'created_at' => 'unix_timestamp',
+        'updated_at' => 'unix_timestamp',
+    ];
+}

tests/Unit/Mutators/HexBinaryMutatorTest.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Weebly\Mutate\Mutators;
+
+use stdClass;
+use PHPUnit\Framework\TestCase;
+
+class HexBinaryMutatorTest extends TestCase
+{
+    /**
+     * @param string $hex
+     * @param string $expected
+     * @dataProvider hexProvider
+     */
+    public function testSerialize($hex, $expected)
+    {
+        $this->assertEquals($expected, (new HexBinaryMutator())->serializeAttribute($hex));
+    }
+
+    /**
+     * @param string $expected
+     * @param string $binary
+     * @dataProvider hexProvider
+     */
+    public function testUnserialize($expected, $binary)
+    {
+        $this->assertEquals($expected, (new HexBinaryMutator())->unserializeAttribute($binary));
+    }
+
+    /**
+     * @return \Iterator
+     */
+    public function hexProvider()
+    {
+        $hexes = [
+            'Hex string of length 2' => ['e7', hex2bin('e7')],
+            'Hex string of length 4' => ['232f', hex2bin('232f')],
+            'Hex string of length 6' => ['0b76e0', hex2bin('0b76e0')],
+            'Hex string of length 8' => ['65c1b7b0', hex2bin('65c1b7b0')],
+            'Hex string of length 10' => ['e2f9995c0b', hex2bin('e2f9995c0b')],
+            'Hex string of length 12' => ['cfc46177b9cd', hex2bin('cfc46177b9cd')],
+            'Hex string of length 14' => ['01f4890a5996c1', hex2bin('01f4890a5996c1')],
+            'Hex string of length 16' => ['d8d3a96d2a441b39', hex2bin('d8d3a96d2a441b39')],
+            'Hex string of length 18' => ['5d87fca1c8f5c2ec21', hex2bin('5d87fca1c8f5c2ec21')],
+            'Hex string of length 20' => ['c334821e50532bd40227', hex2bin('c334821e50532bd40227')],
+        ];
+
+        return $hexes;
+    }
+
+    /**
+     * @param mixed $value
+     * @dataProvider notHexProvider
+     * @expectedException \Weebly\Mutate\Exceptions\MutateException
+     */
+    public function testWrongFormat($value)
+    {
+        (new HexBinaryMutator())->serializeAttribute($value);
+    }
+
+    /**
+     * @return array
+     */
+    public function notHexProvider()
+    {
+        return [
+            'An object cannot be serialized' => [new stdClass],
+            'An int cannot be serialized' => [0],
+            'Floats cannot be serialized' => [0.3],
+            'Only hex strings can be serialiazed' => ['YzMzNDgyMWU1MDUzMmJkNDAy'],
+            'Null cannot be serialized' => [null],
+            'Booleans cannot be serialized' => [true],
+            'Hex strings should have even lengths to be valid bytes representations' => ['a'],
+         ];
+    }
+}

tests/Unit/Mutators/UnixTimestampMutatorTest.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Weebly\Mutate\Mutators;
+
+use Carbon\Carbon;
+use PHPUnit\Framework\TestCase;
+
+class UnixTimestampMutatorTest extends TestCase
+{
+    /**
+     * @param string $carbon
+     * @param string $expected
+     * @dataProvider carbonProvider
+     */
+    public function testSerialize($carbon, $expected)
+    {
+        $this->assertEquals($expected, (new UnixTimestampMutator())->serializeAttribute($carbon));
+    }
+
+    /**
+     * @param string $expected
+     * @param string $binary
+     * @dataProvider carbonProvider
+     */
+    public function testUnserialize($expected, $timestamp)
+    {
+        $unserialized = (new UnixTimestampMutator())->unserializeAttribute($timestamp);
+        $this->assertEquals($expected->year, $unserialized->year);
+        $this->assertEquals($expected->month, $unserialized->month);
+        $this->assertEquals($expected->day, $unserialized->day);
+        $this->assertEquals($expected->hour, $unserialized->hour);
+        $this->assertEquals($expected->minute, $unserialized->minute);
+        $this->assertEquals($expected->second, $unserialized->second);
+    }
+
+    /**
+     * @return \Iterator
+     */
+    public function carbonProvider()
+    {
+        $now = time();
+
+        return [
+            'Now' => [Carbon::createFromTimestamp($now), $now],
+            'Timestamp 1' => [Carbon::createFromTimestamp(1), 1],
+            'Timestamp for max uint32' => [Carbon::createFromTimestamp(pow(2, 32) - 1), pow(2, 32) - 1],
+            'Negative timestamp' => [Carbon::createFromTimestamp(-200), -200],
+            'Timestamp 0' => [Carbon::createFromTimestamp(0), 0],
+        ];
+    }
+}