Merge pull request #201 from gnutix/fix-document-typehint

Fixing type hints on Document that should hint on DocumentInterface

library/Solarium/QueryType/Analysis/Query/Document.php

@@ -38,20 +38,25 @@
  */
 namespace Solarium\QueryType\Analysis\Query;
 use Solarium\Core\Client\Client;
+use Solarium\Exception\RuntimeException;
 use Solarium\QueryType\Analysis\ResponseParser\Document as ResponseParser;
 use Solarium\QueryType\Analysis\RequestBuilder\Document as RequestBuilder;
-use Solarium\QueryType\Select\Result\Document as ResultDocument;
+use Solarium\QueryType\Select\Result\DocumentInterface as SelectDocumentInterface;
+use Solarium\QueryType\Update\Query\Document\DocumentInterface as UpdateDocumentInterface;
 
 /**
  * Analysis document query
  */
 class Document extends Query
 {
+    const DOCUMENT_TYPE_HINT_EXCEPTION_MESSAGE = 'The document argument must either implement
+        \Solarium\QueryType\Select\Result\DocumentInterface or
+        \Solarium\QueryType\Update\Query\Document\DocumentInterface, instance of %s given.';
 
     /**
      * Documents to analyze
      *
-     * @var ResultDocument[]
+     * @var SelectDocumentInterface[]|UpdateDocumentInterface[]
      */
     protected $documents = array();
 
@@ -99,11 +104,16 @@ class Document extends Query
     /**
      * Add a single document
      *
-     * @param  \Solarium\QueryType\Update\Query\Document\Document $document
+     * @param  SelectDocumentInterface|UpdateDocumentInterface $document
      * @return self                                            Provides fluent interface
+     * @throws RuntimeException                                If the given document doesn't have the right interface
      */
     public function addDocument($document)
     {
+        if (!($document instanceof SelectDocumentInterface) && !($document instanceof UpdateDocumentInterface)) {
+            throw new RuntimeException(sprintf(static::DOCUMENT_TYPE_HINT_EXCEPTION_MESSAGE, get_class($document)));
+        }
+
         $this->documents[] = $document;
 
         return $this;
@@ -112,11 +122,19 @@ class Document extends Query
     /**
      * Add multiple documents
      *
-     * @param  \Solarium\QueryType\Update\Query\Document\DocumentInterface[] $documents
+     * @param  SelectDocumentInterface[]|UpdateDocumentInterface[] $documents
      * @return self                                                Provides fluent interface
+     * @throws RuntimeException                                    If any of the given documents does not implement
+     *                                                             any DocumentInterface
      */
     public function addDocuments($documents)
     {
+        foreach ($documents as $document) {
+            if (!($document instanceof SelectDocumentInterface) && !($document instanceof UpdateDocumentInterface)) {
+                throw new RuntimeException(sprintf(static::DOCUMENT_TYPE_HINT_EXCEPTION_MESSAGE, get_class($document)));
+            }
+        }
+
         $this->documents = array_merge($this->documents, $documents);
 
         return $this;
@@ -125,7 +143,7 @@ class Document extends Query
     /**
      * Get all documents
      *
-     * @return ResultDocument[]
+     * @return SelectDocumentInterface[]|UpdateDocumentInterface[]
      */
     public function getDocuments()
     {

library/Solarium/QueryType/Extract/Query.php

@@ -45,7 +45,7 @@ namespace Solarium\QueryType\Extract;
 use Solarium\Core\Query\Query as BaseQuery;
 use Solarium\Core\Client\Client;
 use Solarium\QueryType\Update\ResponseParser as UpdateResponseParser;
-use Solarium\QueryType\Update\Query\Document\Document;
+use Solarium\QueryType\Update\Query\Document\DocumentInterface;
 
 /**
  * Extract query
@@ -131,10 +131,10 @@ class Query extends BaseQuery
      * The fields in the document are indexed together with the generated
      * fields that Solr extracts from the file.
      *
-     * @param  Document $document
+     * @param  DocumentInterface $document
      * @return self
      */
-    public function setDocument($document)
+    public function setDocument(DocumentInterface $document)
     {
         return $this->setOption('document', $document);
     }
@@ -142,7 +142,7 @@ class Query extends BaseQuery
     /**
      * Get the document with literal fields and boost settings
      *
-     * @return Document|null
+     * @return DocumentInterface|null
      */
     public function getDocument()
     {
@@ -394,7 +394,7 @@ class Query extends BaseQuery
      *
      * @param  array    $fields
      * @param  array    $boosts
-     * @return Document
+     * @return DocumentInterface
      */
     public function createDocument($fields = array(), $boosts = array())
     {

library/Solarium/QueryType/Update/Query/Command/Add.php

@@ -38,7 +38,7 @@
  */
 namespace Solarium\QueryType\Update\Query\Command;
 use Solarium\QueryType\Update\Query\Query as UpdateQuery;
-use Solarium\QueryType\Update\Query\Document\Document;
+use Solarium\QueryType\Update\Query\Document\DocumentInterface;
 use Solarium\Exception\RuntimeException;
 
 /**
@@ -70,15 +70,11 @@ class Add extends Command
      * Add a single document
      *
      * @throws RuntimeException
-     * @param  Document         $document
+     * @param  DocumentInterface $document
      * @return self              Provides fluent interface
      */
-    public function addDocument($document)
+    public function addDocument(DocumentInterface $document)
     {
-        if (!($document instanceof Document)) {
-            throw new RuntimeException('Documents must implement the document interface');
-        }
-
         $this->documents[] = $document;
 
         return $this;
@@ -89,9 +85,16 @@ class Add extends Command
      *
      * @param  array|\Traversable $documents
      * @return self               Provides fluent interface
+     * @throws RuntimeException   If any of the given documents does not implement DocumentInterface
      */
     public function addDocuments($documents)
     {
+        foreach ($documents as $document) {
+            if (!($document instanceof DocumentInterface)) {
+                throw new RuntimeException('Documents must implement DocumentInterface.');
+            }
+        }
+
         //if we don't have documents so far, accept arrays or Traversable objects as-is
         if (empty($this->documents)) {
             $this->documents = $documents;
@@ -115,7 +118,7 @@ class Add extends Command
     /**
      * Get all documents
      *
-     * @return Document[]
+     * @return DocumentInterface[]
      */
     public function getDocuments()
     {

library/Solarium/QueryType/Update/Query/Query.php

@@ -354,7 +354,7 @@ class Query extends BaseQuery
      * @param  int               $commitWithin
      * @return self              Provides fluent interface
      */
-    public function addDocument($document, $overwrite = null,
+    public function addDocument(DocumentInterface $document, $overwrite = null,
                                 $commitWithin = null)
     {
         return $this->addDocuments(array($document), $overwrite, $commitWithin);

tests/Solarium/Tests/QueryType/Update/Query/Command/AddTest.php

@@ -63,9 +63,20 @@ class AddTest extends \PHPUnit_Framework_TestCase
 
     public function testAddDocumentWithInvalidDocument()
     {
+        try {
             $doc = new \StdClass();
-        $this->setExpectedException('Solarium\Exception\RuntimeException');
             $this->command->addDocument($doc);
+
+            $this->fail(
+                'The addDocument() method should not accept anything else than DocumentInterface instances.'
+            );
+        } catch (\PHPUnit_Framework_Error $e) {
+            $this->assertContains(
+                'Argument 1 passed to '.get_class($this->command).'::addDocument() must implement interface '.
+                'Solarium\QueryType\Update\Query\Document\DocumentInterface, instance of stdClass given',
+                $e->getMessage()
+            );
+        }
     }
 
     public function testAddDocuments()