Jsonform Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require limenius/jsonform-bundle
   

   Ensure your config/bundles.php includes:

   return [
       // ...
       Limenius\JsonFormBundle\LimeniusJsonFormBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Add to config/packages/limenius_jsonform.yaml:

   limenius_jsonform:
       enabled: true
       routes:
           schema: true  # Enables `/_schema/{form_name}`
   

3. First Use Case: Generate JSON Schema for a Form Define a Symfony form (e.g., src/Form/ExampleType.php):

   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class ExampleType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder
               ->add('name', TextType::class)
               ->add('email', EmailType::class);
       }
   }
   

   Access the schema via:

   /_schema/example
   

   Returns a JSON Schema for the form, usable in jsonform-react or json-editor.

Implementation Patterns

Workflow: Frontend-Backend Form Sync

1. Backend Form Definition Define forms in Symfony as usual (e.g., UserType, ProductType). The bundle auto-generates schemas for all registered forms.

2. Frontend Integration Fetch schemas via API (e.g., /_schema/user):

   fetch('/_schema/user')
       .then(res => res.json())
       .then(schema => {
           // Use with jsonform-react
           const { JsonForm } = require('jsonform-react');
           return <JsonForm schema={schema} />;
       });
   

3. Validation & Submission Use the schema for client-side validation (e.g., with ajv). Submit data to Symfony’s form handler:

   // Controller
   public function submit(ExampleType $form, Request $request) {
       $form->handleRequest($request);
       if ($form->isSubmitted() && $form->isValid()) {
           // Process data
       }
   }
   

Integration Tips

• Dynamic Forms: Use FormFactory to generate schemas for dynamic forms:

  $form = $this->createForm(ExampleType::class);
  $schema = $this->get('limenius_jsonform.schema_generator')->generate($form);
  

• Custom Fields: Extend Liform\Liform to support custom Symfony field types. Example:

  use Liform\Liform;
  use Limenius\JsonFormBundle\Extension\FieldExtensionInterface;
  
  class CustomFieldExtension implements FieldExtensionInterface {
      public function extend(Liform $liform) {
          $liform->addType('custom_field', function ($type) {
              return [
                  'type' => 'string',
                  'title' => $type->getOption('label'),
                  'customProperty' => true,
              ];
          });
      }
  }
  

  Register in services.yaml:

  services:
      App\Extension\CustomFieldExtension:
          tags: [limenius_jsonform.field_extension]
  

Gotchas and Tips

Pitfalls

1. Schema Caching

   • By default, schemas are cached. Clear cache after form changes:

     php bin/console cache:clear
     

   • Disable caching in config/packages/limenius_jsonform.yaml:

     limenius_jsonform:
         cache: false
     

2. Form Name Routing

   • The route /_schema/{form_name} uses the form type’s short class name (e.g., ExampleType → example).
   • Override with options['schema_route_name'] in the form type:

     class ExampleType extends AbstractType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults([
                 'schema_route_name' => 'custom_schema_name',
             ]);
         }
     }
     

3. Complex Field Types

   • Nested forms or collections may require manual schema adjustments. Use Liform’s extend() method to customize:

     $liform->addType('collection', function ($type) {
         return [
             'type' => 'array',
             'items' => $type->getInnerType()->getSchema(),
         ];
     });
     

Debugging

• Validate Schema Output Use JSON Schema Validator to test generated schemas.
• Log Schema Generation Enable debug mode in config/packages/limenius_jsonform.yaml:

  limenius_jsonform:
      debug: true
  

  Check logs for generation details.

Extension Points

1. Custom Schema Generators Override the default generator by binding a service tagged limenius_jsonform.schema_generator:

   services:
       App\Service\CustomSchemaGenerator:
           tags: [limenius_jsonform.schema_generator]
   

2. Post-Processing Schemas Use the limenius_jsonform.schema_processor event listener to modify schemas:

   use Limenius\JsonFormBundle\Event\SchemaEvent;
   
   public function onSchemaProcess(SchemaEvent $event) {
       $event->getSchema()['customProperty'] = 'value';
   }
   

   Register as a service:

   services:
       App\EventListener\SchemaListener:
           tags: [kernel.event_listener, { event: limenius_jsonform.schema_process, method: onSchemaProcess }]
   

Frontend Quirks

• React Integration Ensure jsonform-react is configured to handle Symfony’s schema structure. Example:

  <JsonForm
      schema={schema}
      uischema={{
          'ui:order' => ['name', 'email'],
      }}
  />
  

• Form Data Mapping Client-submitted data must match the schema’s properties. Use DataTransformer or Normalizer in Symfony to handle mismatches.