Improve embed format usage

Added:
- Methods `isValidFormat()` and `assertValidFormat()` to `EmbedRepository`.
- Constants `FORMAT_*` to `EmbedRepositoryInterface` to standardize supported formats.

src/Charcoal/Embed/Action/UpdateEmbedDataAction.php

@@ -46,7 +46,7 @@ public function run(RequestInterface $request, ResponseInterface $response)
     {
         $ident = $request->getParam('ident');
 
-        $results = $this->embedRepository()->saveEmbedData($ident, 'array');
+        $results = $this->embedRepository()->saveEmbedData($ident, self::FORMAT_ARRAY);
 
         if ($results['ident']) {
             $this->setSuccess(true);

src/Charcoal/Embed/Contract/EmbedRepositoryInterface.php

@@ -7,6 +7,10 @@
  */
 interface EmbedRepositoryInterface
 {
+    const FORMAT_ARRAY = 'array';
+    const FORMAT_HTML  = 'html';
+    const FORMAT_SRC   = 'src';
+
     /**
      * @param  string $ident  The embed URI to save from.
      * @param  string $format The embed format.

src/Charcoal/Embed/Mixin/EmbedAwareTrait.php

@@ -2,6 +2,7 @@
 
 namespace Charcoal\Embed\Mixin;
 
+use Charcoal\Embed\Contract\EmbedRepositoryInterface;
 use Charcoal\Translator\Translation;
 use Embed\Embed;
 use Exception;
@@ -100,11 +101,11 @@ private function resolveEmbedFormat($url, $format = null)
             }
         }
 
-        if ($format === 'src') {
+        if ($format === EmbedRepositoryInterface::FORMAT_SRC) {
             return $src;
         }
 
-        if ($format === 'array') {
+        if ($format === EmbedRepositoryInterface::FORMAT_ARRAY) {
             $provider = strtolower($embed->providerName);
 
             // Extract an image preview from embedable iframe.

src/Charcoal/Embed/Service/EmbedRepository.php

@@ -430,7 +430,7 @@ public function embedData($ident)
 
         $item = $this->load($ident);
         if ($item === false) {
-            $item = $this->processEmbed($ident, 'array');
+            $item = $this->processEmbed($ident, self::FORMAT_ARRAY);
             $this->saveItem($item);
         }
 
@@ -632,18 +632,57 @@ public function format()
     }
 
     /**
-     * @param  string $format Format for EmbedRepository.
+     * @param  string $format The embed format.
      * @return self
      */
     public function setFormat($format)
+    {
+        $this->assertValidFormat($format);
+
+        $this->format = $format;
+
+        return $this;
+    }
+
+    /**
+     * Determines if the embed format is valid.
+     *
+     * @param  string $format The format to test.
+     * @return boolean
+     */
+    public function isValidFormat($format)
     {
         switch ($format) {
-            case 'array':
-            case 'src':
-                $this->format = $format;
-                break;
+            case self::FORMAT_ARRAY:
+            case self::FORMAT_HTML:
+            case self::FORMAT_SRC:
+                return true;
         }
 
-        return $this;
+        return false;
+    }
+
+    /**
+     * Asserts that the embed format is valid, throws an exception if not.
+     *
+     * @param  string $format The format to test.
+     * @throws InvalidArgumentException If the format is not a string or unsupported.
+     * @return void
+     */
+    public function assertValidFormat($format)
+    {
+        if (!is_string($format)) {
+            throw new InvalidArgumentException(sprintf(
+                'Unsupported format; must be a string, received %s',
+                (is_object($format) ? get_class($format) : gettype($format))
+            ));
+        }
+
+        if (!$this->isValidFormat($format)) {
+            throw new InvalidArgumentException(sprintf(
+                'Unsupported "%s" format',
+                $format
+            ));
+        }
     }
 }

src/Charcoal/Property/EmbedProperty.php

@@ -19,7 +19,7 @@ class EmbedProperty extends UrlProperty
     /**
      * @var string|null $embedFormat
      */
-    protected $embedFormat = 'array';
+    protected $embedFormat = EmbedRepository::FORMAT_ARRAY;
 
     /**
      * @param  Container $container A Pimple DI container.
@@ -46,6 +46,8 @@ public function embedFormat()
      */
     public function setEmbedFormat($format)
     {
+        $this->embedRepository()->assertValidFormat($format);
+
         $this->embedFormat = $format;
 
         return $this;