[DEV-3393] Add MissingDocumentFieldException and change "meta" to

"fields" to avoid confusion.

Author: frazjp65

src/Document/Document.php

@@ -47,11 +47,11 @@ class Document
     private $_bucket = null;
 
     /**
-     * Document metadata
+     * Document fields
      *
      * @var array
      */
-    private $_meta = [];
+    private $_fields = [];
 
 
     /**
@@ -61,13 +61,13 @@ class Document
      *
      * @param string $doc_id document identifier
      * @param Bucket $bucket document key/value store
-     * @param array  $meta   document metadata
+     * @param array  $fields document fields
      */
-    public function __construct( $doc_id, Bucket $bucket, array $meta = [] )
+    public function __construct( $doc_id, Bucket $bucket, array $fields = [] )
     {
         $this->_id     = (string)$doc_id;
         $this->_bucket = $bucket;
-        $this->_meta   = $meta;
+        $this->_fields = $fields;
     }
 
 
@@ -89,7 +89,16 @@ public function getId()
      */
     public function getProgramId()
     {
-        return $this->_getMetaByName( "programId" );
+        // This existed before MissingDocumentFieldException and
+        // was expected to not throw an exception when it does not exist.
+        try
+        {
+            return (string)$this->_getFieldByName( "programId" );
+        }
+        catch ( MissingDocumentFieldException $e )
+        {
+            return "";
+        }
     }
 
 
@@ -100,7 +109,7 @@ public function getProgramId()
      */
     public function getAgentId()
     {
-        return $this->_getMetaByName( "agentId" );
+        return $this->_getFieldByName( "agentId" );
     }
 
 
@@ -111,7 +120,7 @@ public function getAgentId()
      */
     public function getAgentEntityId()
     {
-        return $this->_getMetaByName( "agentEntityId" );
+        return $this->_getFieldByName( "agentEntityId" );
     }
 
 
@@ -122,7 +131,7 @@ public function getAgentEntityId()
      */
     public function getInitialRatedDate()
     {
-        return $this->_getMetaByName( "initialRatedDate" );
+        return $this->_getFieldByName( "initialRatedDate" );
     }
 
 
@@ -133,7 +142,7 @@ public function getInitialRatedDate()
      */
     public function getStartDate()
     {
-        return $this->_getMetaByName( "startDate" );
+        return $this->_getFieldByName( "startDate" );
     }
 
 
@@ -144,7 +153,7 @@ public function getStartDate()
      */
     public function getAgentName()
     {
-        return $this->_getMetaByName( "agentName" );
+        return $this->_getFieldByName( "agentName" );
     }
 
 
@@ -160,15 +169,19 @@ public function getBucket()
 
 
     /**
-     * Get metadata by key name
+     * Get fields by key name
      *
-     * @param String The name of the key holding the data.
-     *
-     * @return string metadata or empty string if unknown
+     * @param String The name of the key holding the data
+     * @return string field or empty string if unknown
+     * @throws MissingDocumentFieldException when the field does not exist
      */
-    private function _getMetaByName( $name )
+    private function _getFieldByName( $name )
     {
-        $data = &$this->_meta[ $name ];
-        return (string)$data;
+        if ( array_key_exists( $name, $this->_fields ) )
+        {
+            return $this->_fields[ $name ];
+        }
+
+        throw new MissingDocumentFieldException( "Missing field data" );
     }
 }

src/Document/MissingDocumentFieldException.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Missin document field data exception
+ *
+ *  Copyright (C) 2016 LoVullo Associates, Inc.
+ *
+ *  This file is part of libliza-php.
+ *
+ *  libliza-php is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+namespace Lovullo\Liza\Document;
+
+
+/**
+ * Invalid or incomplete document field data were provided
+ *
+ * N.B: This exception should not provide the bad data, as that would leak
+ * implementation details (and potentially very sensitive data); this is a
+ * public-facing exception!
+ */
+class MissingDocumentFieldException
+    extends \Exception
+{
+}

test/Document/DocumentTest.php

@@ -24,7 +24,6 @@
 
 use \Lovullo\Liza\Document\Document as Sut;
 
-
 class DocumentTest
     extends \PHPUnit_Framework_TestCase
 {
@@ -116,11 +115,6 @@ public function emptyGettersDataProvider()
     {
         return [
             [ "getProgramId" ],
-            [ "getAgentId" ],
-            [ "getAgentName" ],
-            [ "getAgentEntityId" ],
-            [ "getInitialRatedDate" ],
-            [ "getStartDate" ],
         ];
     }
 
@@ -139,4 +133,30 @@ public function testEmptyGetters( $methodName )
             )->$methodName()
         );
     }
+
+
+    public function exceptionGettersDataProvider()
+    {
+        return [
+            [ "getAgentId" ],
+            [ "getAgentName" ],
+            [ "getAgentEntityId" ],
+            [ "getInitialRatedDate" ],
+            [ "getStartDate" ],
+        ];
+    }
+
+
+    /**
+     * @dataProvider exceptionGettersDataProvider
+     * @expectedException \Lovullo\Liza\Document\MissingDocumentFieldException
+     */
+    public function testExceptionGetters( $methodName )
+    {
+        $this->createSut(
+            1234,
+            $this->getDummyBucket(),
+            []
+        )->$methodName();
+    }
 }