Liform Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require limenius/liform:^2.0

Add to composer.json if not auto-loaded:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Limenius\\Liform\\": "vendor/limenius/liform/src/"
    }
}

Run composer dump-autoload.

2. First Use Case: Convert a Form to JSON Schema

   use Limenius\Liform\Liform;
   use Symfony\Component\Form\FormBuilderInterface;
   
   // Build a Symfony Form
   $builder = $this->formFactory->createNamedBuilder('user', null, null);
   $builder->add('name', TextType::class);
   $builder->add('email', EmailType::class);
   $builder->add('age', IntegerType::class);
   
   $form = $builder->getForm();
   
   // Convert to JSON Schema (updated for 2.0+)
   $schema = Liform::create()->fromForm($form)->toArray();
   

3. Where to Look First

   • Documentation (check for 2.0 migration guide).
   • src/Limenius/Liform/Liform.php for core functionality.
   • src/Limenius/Liform/Builder/ for form type-specific transformations.
   • New AbstractTransformer class for understanding isRequired() behavior (2.0.1+).

Implementation Patterns

Common Workflows

1. Dynamic Form to Schema Conversion (Updated)

// In a controller or service (2.0+ syntax)
public function getFormSchema(FormBuilderInterface $builder)
{
    $form = $builder->getForm();
    return Liform::create()
        ->fromForm($form)
        ->toArray();
}

2. Checking Field Requirements (2.0.1+)

// Access the AbstractTransformer's isRequired() logic for custom checks
$transformer = Liform::create()->fromForm($form)->getTransformer('name');
$isRequired = $transformer->isRequired(); // Returns boolean (new in 2.0.1)

3. Customizing Schema Output (2.0+)

Liform::create()
    ->fromForm($form)
    ->setOption('required_all_when_empty', true)
    ->setOption('use_full_object_key', true)
    ->toArray();

4. Integration with API Platform (Updated)

use ApiPlatform\Core\DataTransformer\DataTransformerInterface;

class FormSchemaTransformer implements DataTransformerInterface
{
    public function transform($object, string $to, array $context = [])
    {
        $form = $this->formFactory->createNamedBuilder($object->getFormType(), null, $object->getData())
            ->getForm();
        return Liform::create()->fromForm($form)->toArray();
    }
}

5. Handling Nested Forms and Collections (2.0+)

// Example: Form with a collection of items
$builder->add('items', CollectionType::class, [
    'entry_type' => TextType::class,
    'allow_add' => true,
    'allow_delete' => true,
]);

// Liform automatically handles nested schemas for collections
$schema = Liform::create()->fromForm($form)->toArray();
// Result: `items` will be an array with `type: "array"` and `items: { ... }`

Integration Tips

Laravel-Specific (2.0+)

• Service Provider Binding (Updated) Bind Liform as a singleton in AppServiceProvider:

  $this->app->singleton(Liform::class, function ($app) {
      return Liform::create();
  });
  

  Then inject Liform into controllers/services.

• Form Type Extensions (2.0+) Extend Liform's behavior for custom form types by implementing Limenius\Liform\Builder\FormTypeBuilderInterface:

  use Limenius\Liform\Builder\FormTypeBuilderInterface;
  
  class CustomTypeBuilder implements FormTypeBuilderInterface
  {
      public function build(array $config, FormTypeInterface $type, FormBuilderInterface $builder)
      {
          return [
              'type' => 'string',
              'custom_property' => $config['custom_value'] ?? null,
          ];
      }
  }
  

  Register it in Liform's builder stack:

  Liform::create()
      ->addBuilder(new CustomTypeBuilder())
      ->fromForm($form);
  

API-First Development (2.0+)

• Generate OpenAPI/Swagger Schemas (Updated) Use Liform to auto-generate request/response schemas for API endpoints:

  $requestSchema = Liform::create()
      ->fromForm($this->formFactory->createNamedBuilder('UserCreate', null, null)->getForm())
      ->toArray();
  
  $responseSchema = [
      'type' => 'object',
      'properties' => [
          'id' => ['type' => 'integer'],
          'name' => ['type' 'string'],
      ],
  ];
  

Gotchas and Tips

Pitfalls (Updated for 2.0.1+)

1. isRequired() Return Value Changes (2.0.1)

   • Issue: AbstractTransformer::isRequired() now returns a boolean (previously may have returned mixed types).
   • Fix: Ensure custom transformers handle boolean returns explicitly:

     public function isRequired(): bool {
         return $this->form->getConfig()->getOption('required');
     }
     

2. Nested Forms and Circular References (2.0+)

   • Issue: Complex nested forms may cause infinite loops.
   • Fix: Use setOption('max_depth', 3) or manually flatten schemas.

3. Form Data vs. Schema Mismatch (2.0+)

   • Issue: Schema may not match actual form data (e.g., null values for required fields).
   • Fix: Use setOption('ignore_missing_data', false) or leverage isRequired() checks.

4. Custom Form Types Not Recognized (2.0+)

   • Issue: Liform may not handle custom form types.
   • Fix: Implement FormTypeBuilderInterface or extend existing builders.

5. JSON Schema Version Conflicts (2.0+)

   • Issue: Default JSON Schema version may not match API expectations.
   • Fix: Configure Liform to use a specific version:

     Liform::create()->setOption('json_schema_version', 'draft-07');
     

Debugging Tips (2.0+)

1. Inspect Intermediate Steps (Updated) Use toJson() to debug raw output:

   $schema = Liform::create()->fromForm($form);
   dd($schema->toJson()); // Pretty-print JSON for inspection
   

2. Enable Verbose Logging (2.0+)

   Liform::create()->setOption('verbose', true);
   

   Logs transformations for each form field.

3. Check for Deprecated Methods (2.0+)

   • Monitor Liform updates for breaking changes (e.g., isRequired() return type in 2.0.1).

Extension Points (2.0+)

1. Custom JSON Schema Modifiers (Updated) Use setSchemaModifier() to post-process the schema:

   Liform::create()
       ->fromForm($form)
       ->setSchemaModifier(function (array $schema) {
           $schema['additionalProperties'] = false;
           return $schema;
       })
       ->toArray();
   

2. Dynamic Field Mapping (2.0+) Override field names or types dynamically:

   Liform::create()
       ->fromForm($form)
       ->addFieldTransformer('email', function ($field) {
           $field['format'] = 'email-address';
           return $field;
       });
   

3. Integration with Laravel Validation (2.0+) Sync Liform schemas with Laravel's validation rules:

   $rules = $form->getConfig()->getOption('validation_groups');
   $schema = Liform::create()
       ->fromForm($form)
       ->setOption('validation_rules', $rules)
       ->toArray();
   

4. Localization Support (2.0+) Extract translations for form labels/placeholders:

   $translator = app('translator');
   $schema = Liform::create()
       ->fromForm($form)
       ->setTranslator($translator)
       ->toArray();
   

Config Quirks (2.0+)

1. Default Options (Updated) Override defaults globally via a service provider: