raw data can be attached to attachments

CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+1.1.0
+-----
+
+* Added a `$content` attribute to the `Attachment` class to make it possible
+  to attach the raw content to an attachment.
+
 1.0.1
 -----
 

UPGRADE.md

@@ -1,6 +1,12 @@
 UPGRADE
 =======
 
+Upgrading from 1.0 to 1.1
+-------------------------
+
+* Constructing an `Attachment` instance with specifying neither a file URL
+  nor the raw attachment content throws an `\InvalidArgumentException`.
+
 Upgrading from 0.4 to 0.5
 -------------------------
 

composer.json

@@ -34,7 +34,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0.x-dev"
+            "dev-master": "1.1.x-dev"
         }
     }
 }

spec/AttachmentSpec.php

@@ -22,7 +22,8 @@ function its_properties_can_be_read()
             'bd1a58265d96a3d1981710dab8b1e1ed04a8d7557ea53ab0cf7b44c04fd01545',
             $display,
             $description,
-            IRL::fromString('http://tincanapi.com/conformancetest/attachment/fileUrlOnly')
+            IRL::fromString('http://tincanapi.com/conformancetest/attachment/fileUrlOnly'),
+            'some text content'
         );
 
         $this->getUsageType()->equals(IRI::fromString('http://id.tincanapi.com/attachment/supporting_media'))->shouldReturn(true);
@@ -32,6 +33,20 @@ function its_properties_can_be_read()
         $this->getDisplay()->shouldReturn($display);
         $this->getDescription()->shouldReturn($description);
         $this->getFileUrl()->equals(IRL::fromString('http://tincanapi.com/conformancetest/attachment/fileUrlOnly'))->shouldReturn(true);
+        $this->getContent()->shouldReturn('some text content');
+    }
+
+    function it_throws_an_exception_when_an_attachment_does_not_contain_a_file_url_or_raw_content()
+    {
+        $this->beConstructedWith(
+            IRI::fromString('http://id.tincanapi.com/attachment/supporting_media'),
+            'text/plain',
+            18,
+            'bd1a58265d96a3d1981710dab8b1e1ed04a8d7557ea53ab0cf7b44c04fd01545',
+            LanguageMap::create(array('en-US' => 'Text attachment'))
+        );
+
+        $this->shouldThrow('\InvalidArgumentException')->duringInstantiation();
     }
 
     function it_is_not_equal_to_other_attachment_if_usage_types_differ()
@@ -252,7 +267,9 @@ function it_is_not_equal_to_other_attachment_if_only_this_attachment_has_a_file_
             18,
             'bd1a58265d96a3d1981710dab8b1e1ed04a8d7557ea53ab0cf7b44c04fd01545',
             LanguageMap::create(array('en-US' => 'Text attachment')),
-            LanguageMap::create(array('en-US' => 'Text attachment description'))
+            LanguageMap::create(array('en-US' => 'Text attachment description')),
+            null,
+            'some text content'
         );
 
         $this->equals($attachment)->shouldReturn(false);
@@ -266,7 +283,9 @@ function it_is_not_equal_to_other_attachment_if_only_the_other_attachment_has_a_
             18,
             'bd1a58265d96a3d1981710dab8b1e1ed04a8d7557ea53ab0cf7b44c04fd01545',
             LanguageMap::create(array('en-US' => 'Text attachment')),
-            LanguageMap::create(array('en-US' => 'Text attachment description'))
+            LanguageMap::create(array('en-US' => 'Text attachment description')),
+            null,
+            'some text content'
         );
 
         $attachment = new Attachment(

spec/StatementSpec.php

@@ -350,7 +350,9 @@ function it_is_not_equal_with_other_statement_if_number_of_attachments_differs()
             'application/json',
             60,
             'f4135c31e2710764604195dfe4e225884d8108467cc21670803e384b80df88ee',
-            LanguageMap::create(array('en-US' => 'JSON attachment'))
+            LanguageMap::create(array('en-US' => 'JSON attachment')),
+            null,
+            IRL::fromString('http://tincanapi.com/conformancetest/attachment/fileUrlOnly')
         );
         $statement = $this->withAttachments(array($textAttachment, $jsonAttachment));
 
@@ -373,7 +375,9 @@ function it_is_not_equal_with_other_statement_if_attachments_differ()
             'application/json',
             60,
             'f4135c31e2710764604195dfe4e225884d8108467cc21670803e384b80df88ee',
-            LanguageMap::create(array('en-US' => 'JSON attachment'))
+            LanguageMap::create(array('en-US' => 'JSON attachment')),
+            null,
+            IRL::fromString('http://tincanapi.com/conformancetest/attachment/fileUrlOnly')
         );
         $statement = $this->withAttachments(array($textAttachment));
 

src/Attachment.php

@@ -25,6 +25,7 @@ final class Attachment
     private $display;
     private $description;
     private $fileUrl;
+    private $content;
 
     /**
      * @param IRI              $usageType   The type of usage of this attachment
@@ -34,16 +35,23 @@ final class Attachment
      * @param LanguageMap      $display     Localized display name (title)
      * @param LanguageMap|null $description Localized description
      * @param IRL|null         $fileUrl     An IRL at which the attachment data can be retrieved
+     * @param string|null      $content     The raw attachment content, please note that the content is not validated against
+     *                                      the given SHA-2 hash
      */
-    public function __construct(IRI $usageType, $contentType, $length, $sha2, LanguageMap $display, LanguageMap $description = null, IRL $fileUrl = null)
+    public function __construct(IRI $usageType, $contentType, $length, $sha2, LanguageMap $display, LanguageMap $description = null, IRL $fileUrl = null, $content = null)
     {
+        if (null === $fileUrl && null === $content) {
+            throw new \InvalidArgumentException('An attachment cannot be created without a file URL or raw content data.');
+        }
+
         $this->usageType = $usageType;
         $this->contentType = $contentType;
         $this->length = $length;
         $this->sha2 = $sha2;
         $this->display = $display;
         $this->description = $description;
         $this->fileUrl = $fileUrl;
+        $this->content = $content;
     }
 
     public function getUsageType()
@@ -81,6 +89,11 @@ public function getFileUrl()
         return $this->fileUrl;
     }
 
+    public function getContent()
+    {
+        return $this->content;
+    }
+
     public function equals(Attachment $attachment)
     {
         if (!$this->usageType->equals($attachment->usageType)) {