Liform Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle

   composer require limenius/liform-bundle
   

   Ensure your composer.json includes the bundle in the require section.

2. Enable the Bundle Add Limenius\LiformBundle\LiformBundle to the bundles.php (Symfony 4+) or AppKernel.php (Symfony 3-).

3. Configure the Bundle Add the following to config/packages/liform.yaml:

   liform:
       enabled: true
       routes:
           schema: true
       form_types:
           - 'App\Form\YourFormType'
   

4. Generate a Schema Create a form type (e.g., src/Form/YourFormType.php) and annotate it with @Liform\Annotation\AsJsonSchema if needed. Access the schema via:

   /_liform/schema/{form_type_name}
   

5. First Use Case Use the generated schema in a frontend tool like liform-react or json-editor to render a form dynamically. Example:

   import { Liform } from 'liform-react';
   fetch('/_liform/schema/YourFormType')
       .then(response => response.json())
       .then(schema => <Liform schema={schema} />);
   

Implementation Patterns

Core Workflows

1. Schema Generation

   • Automatic: LiformBundle automatically generates JSON schemas for all configured form types.
   • Manual Overrides: Use @Liform\Annotation\AsJsonSchema to customize schema generation for specific fields or forms.

     use Liform\Annotation\AsJsonSchema;
     
     class YourFormType extends AbstractType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('fieldName', TextType::class, [
                 'constraints' => [
                     new NotBlank(),
                 ],
                 // Custom schema options
                 'liform' => [
                     'title' => 'Custom Field Label',
                     'description' => 'Custom description',
                     'pattern' => '^[A-Za-z0-9]+$',
                 ],
             ]);
         }
     }
     

2. Frontend Integration

   • React Example: Use liform-react to render forms from the generated schema.

     <Liform
         schema={schema}
         onChange={handleFormChange}
         formData={initialData}
     />
     

   • Validation: Leverage the schema for client-side validation (e.g., using ajv or json-schema libraries).

3. Dynamic Form Handling

   • Fetch schemas dynamically based on user actions (e.g., dropdown selections) to render conditional forms.
   • Example route configuration:

     liform:
         routes:
             schema: true
             form: true  # Enable form rendering endpoint if needed
     

4. Documentation

   • Host the generated schemas (e.g., /_liform/schema/{form_type_name}) as API documentation for frontend developers.

Integration Tips

1. Symfony Forms to JSON Schema

   • Map Symfony form options (e.g., choices, constraints) to JSON Schema properties. For example:
     • NotBlank constraint → required: true
     • ChoiceType with choices → enum or oneOf in schema.
   • Use liform option in field definitions to override default behavior:

     $builder->add('field', TextType::class, [
         'liform' => [
             'type' => 'string',
             'format' => 'email',
         ],
     ]);
     

2. Custom Form Types

   • Extend Liform\Type\AbstractType to support custom form types in schemas. Example:

     use Liform\Type\AbstractType;
     
     class CustomFormType extends AbstractType {
         public function getName() {
             return 'custom_form_type';
         }
     
         public function getSchema() {
             return [
                 'type' => 'object',
                 'properties' => [
                     'customField' => [
                         'type' => 'string',
                     ],
                 ],
             ];
         }
     }
     

3. API Versioning

   • Version your schemas to avoid breaking changes in the frontend. Example route:

     /api/v1/_liform/schema/{form_type_name}
     

4. Caching

   • Cache generated schemas to reduce server load. Configure in config/packages/liform.yaml:

     liform:
         cache: true
         cache_lifetime: 3600  # 1 hour
     

Gotchas and Tips

Pitfalls

1. Frontend Compatibility

   • Ensure your frontend tool (e.g., liform-react, json-editor) supports the JSON Schema draft version generated by Liform. Default is draft-07.
   • Mismatched draft versions may cause rendering or validation issues.

2. Nested Forms and Collections

   • Complex nested forms (e.g., CollectionType, FormType inside other FormTypes) may require manual schema adjustments. Use liform option to override:

     $builder->add('nestedForm', CollectionType::class, [
         'entry_type' => NestedFormType::class,
         'liform' => [
             'items' => [
                 'type' => 'object',
                 'properties' => [
                     'id' => ['type' => 'integer'],
                     'name' => ['type' => 'string'],
                 ],
             ],
         ],
     ]);
     

3. Circular References

   • Avoid circular references in form types (e.g., FormType A includes FormType B, which includes FormType A). This can cause infinite loops in schema generation.

4. Route Conflicts

   • The default route (/_liform/schema/{form_type_name}) might conflict with other routes. Customize in config/packages/liform.yaml:

     liform:
         routes:
             schema: '/api/schemas/{form_type_name}'
     

5. Deprecated Features

   • Some older versions of LiformBundle may not support newer Symfony form components (e.g., Symfony 5.4+ features). Check compatibility with your Symfony version.

Debugging

1. Schema Validation

   • Validate generated schemas using tools like JSON Schema Validator.
   • Example command to dump raw schema (Symfony 4+):

     $schema = $this->get('liform.schema_generator')->generateSchema('YourFormType');
     var_dump($schema);
     

2. Logging

   • Enable debug mode in config/packages/liform.yaml:

     liform:
         debug: true
     

   • Check Symfony logs (var/log/dev.log) for schema generation errors.

3. Frontend Debugging

   • Use browser dev tools to inspect network requests for schema endpoints. Verify:
     • Correct schema is fetched.
     • No CORS issues (if frontend and backend are separate).
     • Schema matches frontend expectations.

Extension Points

1. Custom Schema Generators

   • Extend Liform\Generator\SchemaGenerator to modify schema generation logic. Example:

     namespace App\Liform;
     
     use Liform\Generator\SchemaGenerator;
     
     class CustomSchemaGenerator extends SchemaGenerator {
         protected function getFieldSchema($field, $options) {
             $schema = parent::getFieldSchema($field, $options);
             // Custom logic here
             return $schema;
         }
     }
     

   • Register the custom generator in services.yaml:

     services:
         App\Liform\CustomSchemaGenerator:
             tags: ['liform.schema_generator']
     

2. Event Listeners

   • Listen to liform.schema_generated event to post-process schemas:

     use Liform\Event\SchemaGeneratedEvent;
     use Symfony\Component\EventDispatcher\GenericEvent;
     
     $dispatcher->addListener('liform.schema_generated', function (SchemaGeneratedEvent $event) {
         $schema = $event->getSchema();
         // Modify schema here
         $event->setSchema($schema);
     });
     

3. Twig Integration

   • Embed schemas directly in Twig templates for dynamic form rendering:

     {% set schema = app.liform.schema_generator.generateSchema('YourFormType') %}
     <script>
         const formSchema = {{ schema|json_encode|raw }};
     </script>
     

4. API Platform Integration

   • Use LiformBundle with API Platform to generate schemas for API resources. Example:

     # config/packages/api_platform.yaml
     api_platform:
         formats:
             jsonld:
                 mime_types: ['application/ld+json']
             json_schema:
                 mime_types: ['application/schema+json']
                 liform: true