ContainerForm interface with put_data method

src/ContainerForm.php

+<?php
+
+namespace WPDesk\Forms;
+
+
+use Psr\Container\ContainerInterface;
+use WPDesk\Persistence\PersistentContainer;
+
+/**
+ * Persistent container support for forms.
+ *
+ * @package WPDesk\Forms
+ */
+interface ContainerForm {
+	/**
+	 * @param ContainerInterface $data
+	 *
+	 * @return void
+	 */
+	public function set_data( $data );
+
+	/**
+	 * Put data from form into a container.
+	 *
+	 * @param PersistentContainer $container Target container.
+	 *
+	 * @return void
+	 */
+	public function put_data( PersistentContainer $container );
+}
+

src/Form.php

@@ -2,8 +2,6 @@
 
 namespace WPDesk\Forms;
 
-
-use Psr\Container\ContainerInterface;
 use WPDesk\View\Renderer\Renderer;
 
 /**
@@ -13,36 +11,67 @@ use WPDesk\View\Renderer\Renderer;
  */
 interface Form {
 	/**
-	 * Checks if form should be active.
+	 * For some reason you may want to disable a form. Returns false when disabled.
 	 *
 	 * @return bool
 	 */
 	public function is_active();
 
+	/**
+	 * Whether form handle_request method was successfully executed.
+	 *
+	 * @return bool
+	 */
 	public function is_submitted();
 
+	/**
+	 * After handle_request or set_data the data in form can be invalid according to field validators.
+	 * Returns false when onle of them says the data is invalid.
+	 *
+	 * @return bool
+	 */
 	public function is_valid();
 
 	/**
 	 * Add array to update data.
 	 *
-	 * @param array|ContainerInterface $request new data to update.
+	 * @param array $request New data to update.
 	 */
 	public function handle_request( $request = array() );
 
 	/**
-	 * @param array|ContainerInterface $data
+	 * Data could be saved in some place. Use this method to transmit them to form.
+	 *
+	 * @param array $data Data for form.
 	 */
 	public function set_data( $data );
 
+	/**
+	 * Use to render the form to string.
+	 *
+	 * @param Renderer $renderer Renderer to render form fields and form-templates.
+	 *
+	 * @return string
+	 */
 	public function render_form( Renderer $renderer );
 
+	/**
+	 * Get data from form. Use after handle_request or set_data.
+	 *
+	 * @return array
+	 */
 	public function get_data();
 
+	/**
+	 * Get data from form. Use after handle_request or set_data.
+	 * The difference get_data is that here you will not get any objects and complex data types besides arrays.
+	 *
+	 * @return array
+	 */
 	public function get_normalized_data();
 
 	/**
-	 * return form Id
+	 * Form if you ever need to have more than one form at once.
 	 *
 	 * @return string
 	 */

src/Form/FormWithFields.php

@@ -3,14 +3,16 @@
 namespace WPDesk\Forms\Form;
 
 use Psr\Container\ContainerInterface;
+use WPDesk\Forms\ContainerForm;
 use WPDesk\Forms\Field;
 use WPDesk\Forms\FieldProvider;
 use WPDesk\Forms\Form;
 use WPDesk\Persistence\Adapter\ArrayContainer;
 use WPDesk\Persistence\ElementNotExistsException;
+use WPDesk\Persistence\PersistentContainer;
 use WPDesk\View\Renderer\Renderer;
 
-class FormWithFields implements Form, FieldProvider {
+class FormWithFields implements Form, ContainerForm, FieldProvider {
 	/**
 	 * Unique form_id.
 	 *
@@ -24,40 +26,57 @@ class FormWithFields implements Form, FieldProvider {
 	 */
 	private $updated_data;
 	/**
+	 * Form fields.
+	 *
 	 * @var Field[]
 	 */
 	private $fields;
 
+	/**
+	 * FormWithFields constructor.
+	 *
+	 * @param array  $fields Form fields.
+	 * @param string $form_id Unique form id.
+	 */
 	public function __construct( array $fields, $form_id = 'form' ) {
 		$this->fields       = $fields;
 		$this->form_id      = $form_id;
 		$this->updated_data = null;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function is_submitted() {
-		return $this->updated_data !== null;
+		return null !== $this->updated_data;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function add_field( Field $field ) {
 		$this->fields[] = $field;
 	}
 
 	/**
-	 * Checks if form should be active.
-	 *
-	 * @return bool
+	 * @inheritDoc
 	 */
 	public function is_active() {
 		return true;
 	}
 
 	/**
-	 * @param Field[] $fields
+	 * Add more fields to form.
+	 *
+	 * @param Field[] $fields Field to add to form.
 	 */
 	public function add_fields( array $fields ) {
 		array_map( [ $this, 'add_field' ], $fields );
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function is_valid() {
 		foreach ( $this->fields as $field ) {
 			$field_value     = isset( $this->updated_data[ $field->get_name() ] ) ? $this->updated_data[ $field->get_name() ] : null;
@@ -88,7 +107,9 @@ class FormWithFields implements Form, FieldProvider {
 	}
 
 	/**
-	 * @param array|ContainerInterface $data
+	 * Data could be saved in some place. Use this method to transmit them to form.
+	 *
+	 * @param array|ContainerInterface $data Data consistent with Form and ContainerForm interface.
 	 */
 	public function set_data( $data ) {
 		if ( is_array( $data ) ) {
@@ -106,12 +127,15 @@ class FormWithFields implements Form, FieldProvider {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function render_form( Renderer $renderer ) {
 		$fields_data = $this->get_data();
 
 		$content = $renderer->render( 'form-start', [
 			'method' => 'POST',
-			'action' => ''
+			'action' => '',
 		] );
 
 		foreach ( $this->get_fields() as $field ) {
@@ -130,6 +154,23 @@ class FormWithFields implements Form, FieldProvider {
 		return $content;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	public function put_data( PersistentContainer $container ) {
+		foreach ( $this->get_fields() as $field ) {
+			$data_key = $field->get_name();
+			if ( ! isset( $this->updated_data[ $data_key ] ) ) {
+				$container->set( $data_key, $field->get_default_value() );
+			} else {
+				$container->set( $data_key, $this->updated_data[ $data_key ] );
+			}
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
 	public function get_data() {
 		$data = $this->updated_data;
 
@@ -143,19 +184,23 @@ class FormWithFields implements Form, FieldProvider {
 		return $data;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function get_fields() {
 		return $this->fields;
 	}
 
 	/**
-	 * return form Id
-	 *
-	 * @return string
+	 * @inheritDoc
 	 */
 	public function get_form_id() {
 		return $this->form_id;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function get_normalized_data() {
 		return $this->get_data();
 	}