Wire up Symfony Forms, Twig extension and add initial docs

Author: simonrjones

README.md

@@ -1,9 +1,17 @@
-# This is my package accessible-forms
+# Accessible forms
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/studio24/accessible-forms.svg?style=flat-square)](https://packagist.org/packages/studio24/accessible-forms)
 [![Tests](https://img.shields.io/github/actions/workflow/status/studio24/accessible-forms/php.yml?branch=main&label=tests&style=flat-square)](https://github.com/studio24/accessible-forms/actions/workflows/php.yml)
 
-This is where your description should go. Try and limit it to a paragraph or two. Consider adding a small example.
+Accessible forms in Laravel and Symfony.
+
+## Todo
+
+Add any notes here on problems to solve:
+
+- What helpers do we need to make form generation easier?
+- Twig in Barryvdh\Form appears to be installed separately to TwigBridge - is this an issue? Twig extension appears to be available for both.
+- Can we automate adding the template paths, currently copy config/form.php across
 
 ## Requirements
 
@@ -17,9 +25,74 @@ You can install the package via [Composer](https://getcomposer.org/):
 composer require studio24/accessible-forms
 ```
 
+### Local install
+During testing you can install this from a local copy via:
+
+```shell
+composer config repositories.local path "~/Sites/studio24/accessible-forms/"
+composer require studio24/accessible-forms:dev-main
+```
+
+To remove this after testing:
+
+```shell
+ddev composer config repositories.local --unset
+ddev composer update
+```
+
+See https://github.com/studio24/dev-playbook/blob/main/composer/testing-local-packages.md
+
 ## Usage
 
-Include some short usage instructions here. If you need more extensive docs save these in docs/ and link to them from here.
+### Laravel
+
+Add the service provider to `bootstrap/providers.php`
+
+```php
+return [
+    Barryvdh\Form\ServiceProvider::class,
+];
+```
+
+To enable TwigExtension in your normal Twig templates (not form twig templates at present) edit `config/twibridge.php`
+
+```php
+return [
+    'extensions' => [
+        'enabled' => [
+            'Studio24\AccessibleForms\Twig\AccessibleFormsExtension',
+        ],
+    ],
+];
+```
+
+Create a form class:
+
+See https://symfony.com/doc/current/forms.html#creating-form-classes
+
+The form processing workflow is:
+
+1. Display form
+2. Form submitted via POST request
+3. Form request data is validated
+4. If pass validation, do something, and redirect to success page
+5. If fail validation, redisplay form with validation messages (and no redirect)
+
+Add form processing code to your controller:
+
+```php
+$form = $this->createForm(ContactForm::class);
+
+$form->handleRequest($request);
+
+if ($form->isSubmitted() && $form->isValid()) {
+    // Do something, e.g. save data
+    return 'Form submitted successfully';
+}
+
+// Display form to user, with validation if submitted and fails validation
+return view('template-name', ['form' => $form->createView()]);
+```
 
 ## Testing
 

composer.json

@@ -2,13 +2,18 @@
     "name": "studio24/accessible-forms",
     "description": "This is my package accessible-forms",
     "keywords": [
-        "studio24"
+        "studio24",
+        "forms",
+        "accessibility",
+        "laravel",
+        "symfony"
     ],
     "type": "library",
     "license": "MIT",
     "homepage": "https://github.com/studio24/accessible-forms",
     "require": {
-        "php": "^8.2"
+        "php": "^8.2",
+        "barryvdh/laravel-form-bridge": "^0.7.4"
     },
     "require-dev": {
         "phpstan/phpstan": "^2.1",
@@ -27,6 +32,9 @@
         }
     },
     "scripts": {
+        "post-install-cmd": [
+            "@php -r \"file_exists('config/form.php') || copy('vendor/studio24/accessible-forms/config/form.php', 'config/form.php');\""
+        ],
         "test": "./vendor/bin/phpunit",
         "cs": "./vendor/bin/phpcs",
         "format": "./vendor/bin/phpcbf",

config/form.php

@@ -0,0 +1,32 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Form theme
+    |--------------------------------------------------------------------------
+    |
+    | Set the template to render the form.
+    |
+    | See https://symfony.com/doc/current/form/form_themes.html
+    */
+    'theme' => 'accessible-forms.html.twig',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Form template directories
+    |--------------------------------------------------------------------------
+    |
+    | Add custom template directories to render the form.
+    |
+    | See http://symfony.com/doc/current/form/form_customization.html
+    */
+    'template_directories' => [
+        __DIR__ . '/../vendor/studio24/accessible-forms/src/Resources/views/form'
+    ],
+
+    'defaults' => [
+        'required' => true,
+    ]
+];

src/AccessibleForms.php

@@ -0,0 +1,7 @@
+{# Extends vendor/symfony/twig-bridge/Resources/views/Form/form_div_layout.html.twig #}
+{% use 'form_div_layout.html.twig' %}
+
+{%- block form_label_content -%}
+    {%- set name = "A11Y " ~ name -%}
+    {{- parent() -}}
+{%- endblock form_label_content -%}

src/Resources/views/Form/accessible-forms.html.twig

@@ -0,0 +1,24 @@
+<?php
+declare(strict_types=1);
+
+namespace Studio24\AccessibleForms\Twig;
+
+use Twig\Extension\AbstractExtension;
+use Twig\TwigFilter;
+
+class AccessibleFormsExtension extends AbstractExtension
+{
+    public function getFilters()
+    {
+        return [
+            new TwigFilter('validation_message', [$this, 'validationMessage']),
+        ];
+    }
+
+    public function validationMessage(string $title): string
+    {
+        // @todo process this message based on form validation
+        return "There are X problems with your request - " . $title;
+    }
+
+}