Repository Forms Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require ezsystems/repository-forms
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="EzSystems\RepositoryForms\EzSystemsRepositoryFormsServiceProvider"
   

2. Basic Setup Register the form type in your config/repository-forms.php:

   'form_types' => [
       'your_form_type' => [
           'class' => \YourNamespace\FormType::class,
           'label' => 'Your Form Label',
       ],
   ],
   

3. First Use Case Create a simple form type extending AbstractFormType:

   use EzSystems\RepositoryForms\Form\FieldType\AbstractFormType;
   
   class YourFormType extends AbstractFormType
   {
       public function getName()
       {
           return 'your_form_type';
       }
   
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder
               ->add('field_name', TextType::class)
               ->add('save', SubmitType::class);
       }
   }
   

   Use it in a controller:

   use EzSystems\RepositoryForms\Form\FormHandler;
   
   public function handleForm(Request $request, FormHandler $formHandler)
   {
       $form = $formHandler->createForm('your_form_type');
       $form->handleRequest($request);
   
       if ($form->isSubmitted() && $form->isValid()) {
           $data = $form->getData();
           // Process data...
       }
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Form Building Use FormBuilderInterface to dynamically add fields based on conditions:

   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       if ($options['show_extra_field']) {
           $builder->add('extra_field', CheckboxType::class);
       }
   }
   

2. Integration with Symfony Forms Leverage Symfony’s form components (e.g., FormEvents, DataTransformers) for validation or data mapping:

   $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $data = $event->getData();
       $event->getForm()->add('dynamic_field', TextType::class, [
           'label' => $data->getLabel(),
       ]);
   });
   

3. Repository Integration Use EzSystems\RepositoryForms\Repository\RepositoryInterface to interact with content repositories:

   public function __construct(private RepositoryInterface $repository) {}
   
   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $content = $this->repository->getContent($options['content_id']);
       $builder->add('title', TextType::class, [
           'data' => $content->getFieldValue('title'),
       ]);
   }
   

4. Form Submissions Handle submissions via FormHandler:

   $formHandler->submitForm('your_form_type', $data, $options);
   

Best Practices

• Reuse Form Types: Extend existing form types to avoid duplication.
• Validation: Use Symfony’s validators or custom constraints for robust validation.
• Options Injection: Pass configuration via $options to make forms flexible.

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides Ensure config/repository-forms.php is published and updated if extending default behavior. Missing keys may cause silent failures.

2. Form Type Registration Forgetting to register the form type in the config will result in FormTypeNotFoundException. Verify the class path and name are correct.

3. Data Binding Issues If fields don’t bind data, check:

   • The getName() method matches the config key.
   • The buildForm() method correctly maps field names to Symfony form types.

4. Repository Dependency If using RepositoryInterface, ensure the service is bound in Laravel’s container:

   $this->app->bind(RepositoryInterface::class, function ($app) {
       return new YourRepository();
   });
   

Debugging Tips

• Enable Symfony Debug Toolbar: Helps inspect form submissions and validation errors.
• Log Form Events: Add listeners to log form lifecycle events:

  $builder->addEventListener(FormEvents::SUBMIT, function (FormEvent $event) {
      \Log::debug('Form submitted', ['data' => $event->getData()]);
  });
  

Extension Points

1. Custom Field Types Extend AbstractFieldType to create reusable field components:

   class CustomFieldType extends AbstractFieldType
   {
       public function getParent()
       {
           return TextType::class;
       }
   
       public function configureOptions(OptionsResolver $resolver)
       {
           $resolver->setDefaults([
               'custom_option' => true,
           ]);
       }
   }
   

2. Form Events Subscribe to FormEvents (e.g., PRE_SUBMIT, POST_SUBMIT) for cross-cutting logic:

   $builder->addEventListener(FormEvents::PRE_SUBMIT, function (FormEvent $event) {
       $data = $event->getData();
       $data['processed'] = true;
       $event->setData($data);
   });
   

3. Validation Groups Use Symfony’s validation groups for multi-step forms:

   $builder->add('field', TextType::class, [
       'constraints' => [
           new NotBlank(['groups' => ['step1']]),
       ],
   ]);