diff --git a/src/ContainerForm.php b/src/ContainerForm.php new file mode 100644 index 0000000000000000000000000000000000000000..1d056b6cacd598007ecc177b29be31b4d7770ed0 --- /dev/null +++ b/src/ContainerForm.php @@ -0,0 +1,31 @@ +<?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 ); +} + diff --git a/src/Form.php b/src/Form.php index 3390e5ba81f15d94f9352b199613e37ee99555ce..7450b2b1203750d62862f8af3b9980f3cf6b47e2 100644 --- a/src/Form.php +++ b/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 */ diff --git a/src/Form/FormWithFields.php b/src/Form/FormWithFields.php index ed84a0c6bd0389af3839054cddb4174f949ffc5c..0e549baf465a8b1c7818e708f1f62b62c2110a24 100644 --- a/src/Form/FormWithFields.php +++ b/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(); }