11# HTTP based Stepped Form
22
3- The package is based on the
4- [ Stepped Form package] ( https://github.com/alexxxxkkk/stepped-form ) and
5- normalizes data into the Response instances.
3+ The package is based on the [ Stepped Form package] ( https://github.com/lexalium/stepped-form ) and works with
4+ HTTP response and requests (transforms form exception into Response and renders or redirects depending on base
5+ form return value).
6+
7+ <a id =" readme-top " mame =" readme-top " ></a >
8+
9+ Table of Contents
10+
11+ 1 . [ Requirements] ( #requirements )
12+ 2 . [ Installation] ( #installation )
13+ 3 . [ Usage] ( #usage )
14+ - [ Exception Normalizers] ( #exception-normalizers )
15+ 4 . [ License] ( #license )
16+
17+ ---
618
719## Requirements
820
9- ** PHP:** ^8.0
21+ ** PHP:** >=8.1
1022
1123## Installation
1224
@@ -16,14 +28,168 @@ Via Composer
1628composer require lexal/http-stepped-form
1729```
1830
19- ## Resources
31+ ## Usage
32+
33+ 1 . Create a base [ Stepped Form] ( https://github.com/lexalium/stepped-form ) .
34+ 2 . Declare your form settings.
35+ ``` php
36+ use Lexal\HttpSteppedForm\Settings\FormSettingsInterface;
37+ use Lexal\SteppedForm\Step\StepKey;
38+
39+ final class FormSettings implements FormSettingsInterface
40+ {
41+ public function getStepUrl(StepKey $key): string
42+ {
43+ // return step URL
44+ }
45+
46+ public function getUrlBeforeStart(): string
47+ {
48+ // returns a URL to redirect to when there is no previously renderable step
49+ }
50+
51+ public function getUrlAfterFinish(): string
52+ {
53+ // return a URL to redirect to when the form was finishing
54+ }
55+ }
56+
57+ $formSettings = new FormSettings();
58+ ```
59+
60+ 3 . Create a Redirector. The Redirector creates and returns Redirect Response.
61+ ``` php
62+ use Lexal\HttpSteppedForm\Routing\RedirectorInterface;
63+ use Symfony\Component\HttpFoundation\Response;
64+
65+ final class Redirector implements RedirectorInterface
66+ {
67+ public function redirect(string $url, array $errors = []): Response
68+ {
69+ // create and return redirect response
70+ }
71+ }
72+
73+ $redirector = new Redirector();
74+ ```
75+
76+ 4 . Create a Renderer. The Renderer crates and returns Response by template definition.
77+ ``` php
78+ use Lexal\HttpSteppedForm\Renderer\RendererInterface;
79+ use Lexal\SteppedForm\Entity\TemplateDefinition;
80+ use Symfony\Component\HttpFoundation\Response;
81+
82+ final class Renderer implements RendererInterface
83+ {
84+ public function render(TemplateDefinition $definition): Response
85+ {
86+ // create and return response
87+ }
88+ }
89+
90+ $renderer = new Renderer();
91+ ```
92+
93+ 5 . Create an Exception Normalizer.
94+ ``` php
95+ use Lexal\HttpSteppedForm\ExceptionNormalizer\ExceptionNormalizer;
96+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\AlreadyStartedExceptionNormalizer;
97+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\DefaultExceptionNormalizer;
98+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\EntityNotFoundExceptionNormalizer;
99+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\FormIsNotStartedExceptionNormalizer;
100+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\StepNotFoundExceptionNormalizer;
101+ use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\StepNotRenderableExceptionNormalizer;
102+
103+ $normalizer = new ExceptionNormalizer([
104+ new AlreadyStartedExceptionNormalizer($redirector),
105+ new EntityNotFoundExceptionNormalizer($redirector),
106+ new FormIsNotStartedExceptionNormalizer($redirector),
107+ new StepNotRenderableExceptionNormalizer(),
108+ new StepNotFoundExceptionNormalizer(),
109+ new DefaultExceptionNormalizer(),
110+ ]);
111+ ```
112+
113+ 6 . Create a Stepped Form.
114+ ``` php
115+ use Lexal\HttpSteppedForm\SteppedForm;
116+
117+ $form = new SteppedForm(
118+ /* a base stepped form from the point 1 */,
119+ $formSettings,
120+ $redirector,
121+ $renderer,
122+ $normalizer,
123+ );
124+ ```
125+
126+ 7 . Use Stepped Form in your application.
127+ ``` php
128+ /*
129+ * Starts a new form session.
130+ * Returns redirect response to the next step or URL after form finish.
131+ */
132+ $form->start(/* an entity for initializing a form state */);
133+
134+ /* Renders step by its definition */
135+ $form->render('key');
136+
137+ /*
138+ * Handles a step logic and saves a new form state.
139+ * Returns redirect response to the next step or URL after form finish.
140+ */
141+ $form->handle('key', /* request instance*/);
142+
143+ /* Cancels form session and returns redirect response to the given URL */
144+ $form->cancel(/* any URL */);
145+ ```
146+
147+ <div style =" text-align right " >(<a href =" #readme-top " >back to top</a >)</div >
148+
149+ ## Exception Normalizers
150+
151+ Exception Normalizers are used for the normalizing Stepped Form exceptions into the Response instance. Create class
152+ that implements ` ExceptionNormalizerInterface ` to create your own exception normalizer.
153+
154+ ``` php
155+ use Lexal\HttpSteppedForm\Settings\FormSettingsInterface;
156+ use Lexal\HttpSteppedForm\ExceptionNormalizer\ExceptionNormalizerInterface;
157+ use Lexal\SteppedForm\Exception\AlreadyStartedException;
158+ use Lexal\SteppedForm\Exception\SteppedFormException;
159+ use Symfony\Component\HttpFoundation\Response;
160+
161+ final class CustomExceptionNormalizer implements ExceptionNormalizerInterface
162+ {
163+ public function supportsNormalization(SteppedFormException $exception): bool
164+ {
165+ return $exception instanceof AlreadyStartedException;
166+ }
167+
168+ public function normalize(SteppedFormException $exception, FormSettingsInterface $formSettings): Response
169+ {
170+ // return custom response object
171+ return new Response();
172+ }
173+ }
174+ ```
175+
176+ The package already contains normalizers for all available exceptions:
177+ 1 . ` AlreadyStartedExceptionNormalizer ` - redirects to the current renderable step.
178+ 2 . ` EntityNotFoundExceptionNormalizer ` - redirects with errors to the previously renderable step or the URL
179+ before form start.
180+ 3 . ` FormIsNotStartedExceptionNormalizer ` - redirects with errors to the URL before form start.
181+ 4 . ` StepNotFoundExceptionNormalizer ` - returns 404 HTTP status code.
182+ 5 . ` StepNotRenderableExceptionNormalizer ` - returns 404 HTTP status code.
183+ 6 . ` SteppedFormErrorsExceptionNormalizer ` - redirects with errors to the previously renderable step or the URL
184+ before form start.
185+ 7 . ` StepIsNotSubmittedExceptionNormalizer ` - redirects with errors to the previously renderable step or the URL
186+ before form start.
187+ 8 . ` DefaultExceptionNormalizer ` - rethrows exception.
20188
21- 1 . [ Exception Normalizer] ( docs/EXCEPTION_NORMALIZER.md ) .
22- 2 . [ How To Use] ( docs/USAGE.md ) .
189+ <div style =" text-align right " >(<a href =" #readme-top " >back to top</a >)</div >
23190
24191---
25192
26193## License
27194
28- HTTP Stepped Form is licensed under the MIT License. See
29- [ LICENSE] ( LICENSE ) for the full license text.
195+ HTTP Stepped Form is licensed under the MIT License. See [ LICENSE] ( LICENSE ) for the full license text.
0 commit comments