From 601ec5cb7a654de0584f85be31d847fead3ce13f Mon Sep 17 00:00:00 2001
From: Matias Griese <matias@trilbymedia.com>
Date: Fri, 21 Jun 2019 11:47:21 +0300
Subject: [PATCH] Added `FormFlashInterface`

---
 CHANGELOG.md                                  |   2 +
 system/src/Grav/Common/Form/FormFlash.php     |   3 +-
 system/src/Grav/Framework/Form/FormFlash.php  | 207 +++++++++---------
 .../Form/Interfaces/FormFlashInterface.php    | 167 ++++++++++++++
 4 files changed, 275 insertions(+), 104 deletions(-)
 create mode 100644 system/src/Grav/Framework/Form/Interfaces/FormFlashInterface.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56abeafd5..b90fbb37a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 1. [](#new)
     * Added `FormTrait::getAllFlashes()` method to get all the available form flash objects for the form
     * Added creation and update timestamps to `FormFlash` objects
+1. [](#improved)
+    * Added `FormFlashInterface`
 1. [](#bugfix)
     * Fixed error in `ImageMedium::url()` if the image cache folder does not exist
     * Fixed empty form flash name after file upload or form state update
diff --git a/system/src/Grav/Common/Form/FormFlash.php b/system/src/Grav/Common/Form/FormFlash.php
index b56540425..d3d037041 100644
--- a/system/src/Grav/Common/Form/FormFlash.php
+++ b/system/src/Grav/Common/Form/FormFlash.php
@@ -12,10 +12,11 @@ namespace Grav\Common\Form;
 use Grav\Common\Filesystem\Folder;
 use Grav\Common\Grav;
 use Grav\Common\User\Interfaces\UserInterface;
+use Grav\Framework\Form\FormFlash as FrameworkFormFlash;
 use RocketTheme\Toolbox\File\YamlFile;
 use RocketTheme\Toolbox\ResourceLocator\UniformResourceLocator;
 
-class FormFlash extends \Grav\Framework\Form\FormFlash
+class FormFlash extends FrameworkFormFlash
 {
     /**
      * @param string $sessionId
diff --git a/system/src/Grav/Framework/Form/FormFlash.php b/system/src/Grav/Framework/Form/FormFlash.php
index b971d5d9c..eb35a72d1 100644
--- a/system/src/Grav/Framework/Form/FormFlash.php
+++ b/system/src/Grav/Framework/Form/FormFlash.php
@@ -11,10 +11,11 @@ namespace Grav\Framework\Form;
 
 use Grav\Common\Filesystem\Folder;
 use Grav\Common\Utils;
+use Grav\Framework\Form\Interfaces\FormFlashInterface;
 use Psr\Http\Message\UploadedFileInterface;
 use RocketTheme\Toolbox\File\YamlFile;
 
-class FormFlash implements \JsonSerializable
+class FormFlash implements FormFlashInterface
 {
     /** @var string */
     protected $sessionId;
@@ -55,10 +56,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * FormFlashObject constructor.
-     * @param string $sessionId
-     * @param string $uniqueId
-     * @param string|null $formName
+     * @inheritDoc
      */
     public function __construct(string $sessionId, string $uniqueId, string $formName = null)
     {
@@ -90,23 +88,56 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @return string
+     * @inheritDoc
+     */
+    public function getSessionId(): string
+    {
+        return $this->sessionId;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUniqueId(): string
+    {
+        return $this->uniqueId;
+    }
+
+    /**
+     * @inheritDoc
      */
     public function getFormName(): string
     {
         return $this->formName;
     }
 
+
     /**
-     * @return string
+     * @inheritDoc
      */
-    public function getUniqieId(): string
+    public function getUrl(): string
     {
-        return $this->uniqueId;
+        return $this->url;
     }
 
     /**
-     * @return int
+     * @inheritDoc
+     */
+    public function getUsername(): string
+    {
+        return $this->user['username'] ?? '';
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUserEmail(): string
+    {
+        return $this->user['email'] ?? '';
+    }
+
+    /**
+     * @inheritDoc
      */
     public function getCreatedTimestamp(): int
     {
@@ -114,15 +145,32 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @return int
+     * @inheritDoc
      */
     public function getUpdatedTimestamp(): int
     {
         return $this->updatedTimestamp;
     }
 
+
     /**
-     * @return bool
+     * @inheritDoc
+     */
+    public function getData(): ?array
+    {
+        return $this->data;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setData(?array $data): void
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * @inheritDoc
      */
     public function exists(): bool
     {
@@ -130,7 +178,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @return $this
+     * @inheritDoc
      */
     public function save(): self
     {
@@ -151,6 +199,9 @@ class FormFlash implements \JsonSerializable
         return $this;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function delete(): self
     {
         if ($this->sessionId) {
@@ -163,75 +214,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @return string
-     */
-    public function getUrl(): string
-    {
-        return $this->url;
-    }
-
-    /**
-     * @param string $url
-     * @return $this
-     */
-    public function setUrl(string $url): self
-    {
-        $this->url = $url;
-
-        return $this;
-    }
-
-    /**
-     * @return string
-     */
-    public function getUsername(): string
-    {
-        return $this->user['username'] ?? '';
-    }
-
-    /**
-     * @return string
-     */
-    public function getUserEmail(): string
-    {
-        return $this->user['email'] ?? '';
-    }
-
-    /**
-     * @param string|null $username
-     * @return $this
-     */
-    public function setUserName(string $username = null): self
-    {
-        $this->user['username'] = $username;
-
-        return $this;
-    }
-
-    /**
-     * @param string|null $email
-     * @return $this
-     */
-    public function setUserEmail(string $email = null): self
-    {
-        $this->user['email'] = $email;
-
-        return $this;
-    }
-
-    public function getData(): ?array
-    {
-        return $this->data;
-    }
-
-    public function setData(?array $data): void
-    {
-        $this->data = $data;
-    }
-
-    /**
-     * @param string $field
-     * @return array
+     * @inheritDoc
      */
     public function getFilesByField(string $field): array
     {
@@ -247,8 +230,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @param bool $includeOriginal
-     * @return array
+     * @inheritDoc
      */
     public function getFilesByFields($includeOriginal = false): array
     {
@@ -264,12 +246,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * Add uploaded file to the form flash.
-     *
-     * @param UploadedFileInterface $upload
-     * @param string|null $field
-     * @param array|null $crop
-     * @return string Return name of the file
+     * @inheritDoc
      */
     public function addUploadedFile(UploadedFileInterface $upload, string $field = null, array $crop = null): string
     {
@@ -295,12 +272,7 @@ class FormFlash implements \JsonSerializable
 
 
     /**
-     * Add existing file to the form flash.
-     *
-     * @param string $filename
-     * @param string $field
-     * @param array $crop
-     * @return bool
+     * @inheritDoc
      */
     public function addFile(string $filename, string $field, array $crop = null): bool
     {
@@ -321,11 +293,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * Remove any file from form flash.
-     *
-     * @param string $name
-     * @param string $field
-     * @return bool
+     * @inheritDoc
      */
     public function removeFile(string $name, string $field = null): bool
     {
@@ -357,7 +325,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * Clear form flash from all uploaded files.
+     * @inheritDoc
      */
     public function clearFiles()
     {
@@ -371,7 +339,7 @@ class FormFlash implements \JsonSerializable
     }
 
     /**
-     * @return array
+     * @inheritDoc
      */
     public function jsonSerialize(): array
     {
@@ -389,6 +357,39 @@ class FormFlash implements \JsonSerializable
         ];
     }
 
+    /**
+     * @param string $url
+     * @return $this
+     */
+    public function setUrl(string $url): self
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+
+    /**
+     * @param string|null $username
+     * @return $this
+     */
+    public function setUserName(string $username = null): self
+    {
+        $this->user['username'] = $username;
+
+        return $this;
+    }
+
+    /**
+     * @param string|null $email
+     * @return $this
+     */
+    public function setUserEmail(string $email = null): self
+    {
+        $this->user['email'] = $email;
+
+        return $this;
+    }
+
     /**
      * @return string
      */
diff --git a/system/src/Grav/Framework/Form/Interfaces/FormFlashInterface.php b/system/src/Grav/Framework/Form/Interfaces/FormFlashInterface.php
new file mode 100644
index 000000000..470e845c6
--- /dev/null
+++ b/system/src/Grav/Framework/Form/Interfaces/FormFlashInterface.php
@@ -0,0 +1,167 @@
+<?php
+
+/**
+ * @package    Grav\Framework\Form
+ *
+ * @copyright  Copyright (C) 2015 - 2019 Trilby Media, LLC. All rights reserved.
+ * @license    MIT License; see LICENSE file for details.
+ */
+
+namespace Grav\Framework\Form\Interfaces;
+
+use Psr\Http\Message\UploadedFileInterface;
+
+interface FormFlashInterface extends \JsonSerializable
+{
+    /**
+     * @param string $sessionId
+     * @param string $uniqueId
+     * @param string|null $formName
+     */
+    public function __construct(string $sessionId, string $uniqueId, string $formName = null);
+
+    /**
+     * Get session Id associated to this form instance.
+     *
+     * @return string
+     */
+    public function getSessionId(): string;
+
+    /**
+     * Get unique identifier associated to this form instance.
+     *
+     * @return string
+     */
+    public function getUniqueId(): string;
+
+    /**
+     * Get form name associated to this form instance.
+     *
+     * @return string
+     */
+    public function getFormName(): string;
+
+    /**
+     * Get URL associated to this form instance.
+     *
+     * @return string
+     */
+    public function getUrl(): string;
+
+    /**
+     * Get username from the user who was associated to this form instance.
+     *
+     * @return string
+     */
+    public function getUsername(): string;
+
+    /**
+     * Get email from the user who was associated to this form instance.
+     *
+     * @return string
+     */
+    public function getUserEmail(): string;
+
+
+    /**
+     * Get creation timestamp for this form flash.
+     *
+     * @return int
+     */
+    public function getCreatedTimestamp(): int;
+
+    /**
+     * Get last updated timestamp for this form flash.
+     *
+     * @return int
+     */
+    public function getUpdatedTimestamp(): int;
+
+    /**
+     * Get raw form data.
+     *
+     * @return array|null
+     */
+    public function getData(): ?array;
+
+    /**
+     * Set raw form data.
+     *
+     * @param array|null $data
+     */
+    public function setData(?array $data): void;
+
+    /**
+     * Check if this form flash exists.
+     *
+     * @return bool
+     */
+    public function exists(): bool;
+
+    /**
+     * Save this form flash.
+     *
+     * @return $this
+     */
+    public function save();
+
+    /**
+     * Delete this form flash.
+     */
+    public function delete();
+
+    /**
+     * Get all files associated to a form field.
+     *
+     * @param string $field
+     * @return array
+     */
+    public function getFilesByField(string $field): array;
+
+    /**
+     * Get all files grouped by the associated form fields.
+     *
+     * @param bool $includeOriginal
+     * @return array
+     */
+    public function getFilesByFields($includeOriginal = false): array;
+
+    /**
+     * Add uploaded file to the form flash.
+     *
+     * @param UploadedFileInterface $upload
+     * @param string|null $field
+     * @param array|null $crop
+     * @return string Return name of the file
+     */
+    public function addUploadedFile(UploadedFileInterface $upload, string $field = null, array $crop = null): string;
+
+    /**
+     * Add existing file to the form flash.
+     *
+     * @param string $filename
+     * @param string $field
+     * @param array $crop
+     * @return bool
+     */
+    public function addFile(string $filename, string $field, array $crop = null): bool;
+
+    /**
+     * Remove any file from form flash.
+     *
+     * @param string $name
+     * @param string $field
+     * @return bool
+     */
+    public function removeFile(string $name, string $field = null): bool;
+
+    /**
+     * Clear form flash from all uploaded files.
+     */
+    public function clearFiles();
+
+    /**
+     * @return array
+     */
+    public function jsonSerialize(): array;
+}