Getting Started

Installation:

composer require eekes/sulu-form-city-select-bundle

Eekes\Sulu\FormCitySelectBundle\EekesSuluFormCitySelectBundle::class => ['all' => true],

First Use Case:
- Access the City Select field in Sulu’s form builder under available form fields.
- Configure the field in your Sulu form definition (e.g., config/forms.yml or via the admin UI).
- Test the field in a frontend form to ensure cities are selectable and submitted correctly.
Where to Look First:
- Sulu Form Documentation: Review how to add custom fields to Sulu forms.
- Bundle Configuration: Check for any required config (e.g., API keys for city data) in config/packages/eekes_sulu_form_city_select.yaml.
- Frontend Integration: Verify the field renders correctly in your Sulu frontend templates (e.g., Resources/views/forms/_city_select.html.twig).

Implementation Patterns

1. Basic Field Integration

Add to a Sulu Form:

# config/forms.yml
my_form:
    fields:
        city:
            type: city_select
            label: "Select a City"
            options:
                required: true
                placeholder: "Choose a city..."

Access Submitted Data:

public function store(Request $request)
{
    $city = $request->input('city'); // e.g., "Berlin" or "New York"
    // Process city data (e.g., save to database or use in logic)
}

2. Dynamic City Data

Customize City Source: If the bundle fetches cities from an external API, configure it in config/packages/eekes_sulu_form_city_select.yaml:

eekes_sulu_form_city_select:
    api:
        enabled: true
        endpoint: "https://api.example.com/cities"
        cache_ttl: 3600 # Cache cities for 1 hour

Override City List: Use a service to inject custom city data:

// src/Service/CityProvider.php
class CityProvider implements CityProviderInterface
{
    public function getCities(): array
    {
        return [
            ['id' => 1, 'name' => 'Paris'],
            ['id' => 2, 'name' 'London'],
        ];
    }
}

Bind the service in services.yaml:

services:
    App\Service\CityProvider: ~
eekes_sulu_form_city_select.city_provider: '@App\Service\CityProvider'

3. Frontend Customization

Extend Twig Templates: Override the default template for the city select field:
```
php artisan vendor:publish --tag=sulu-form-city-select-templates
```
Customize templates/forms/fields/city_select.html.twig to add classes, icons, or validation messages.

Add JavaScript Behavior: Use Sulu’s form event system to attach custom logic:

// assets/js/app.js
Sulu.Form.on('citySelect:change', function(event) {
    const city = event.detail.value;
    console.log('Selected city:', city);
    // Trigger additional actions (e.g., load city-specific data)
});

4. Backend Processing

Validate City Input:

$request->validate([
    'city' => 'required|string|exists:cities,name', // Assuming a `cities` table
]);

Use City Data: Fetch city details (e.g., coordinates, region) from a database or API:

$cityData = City::where('name', $request->city)->first();
$coordinates = $cityData->coordinates; // e.g., ["lat" => 52.5200, "lng" => 13.4050]

5. Localization

Translate City Names: Use Sulu’s translation system to localize city labels:

# translations/messages.en.yml
city_select:
    paris: "Paris (France)"
    london: "London (UK)"

Reference translations in your form:

fields:
    city:
        options:
            choices:
                paris: "%city_select.paris%"
                london: "%city_select.london%"

Gotchas and Tips

Pitfalls

Missing API Configuration:
- If the bundle relies on an external API (e.g., for city data), ensure the endpoint is configured and accessible. Test with curl or Postman before integrating:
```
curl https://api.example.com/cities
```
- Fix: Set api.enabled: false in config if using a custom provider, or debug API errors in Sulu logs (var/log/dev.log).
Caching Issues:
- City data cached via the bundle may not update immediately. Clear the cache after changes:
```
php artisan cache:clear
php artisan sulu:cache:clear
```
- Tip: Use cache_ttl: 0 in config for development to bypass caching.
Field Not Appearing in Form Builder:
- Ensure the bundle is enabled in bundles.php and dependencies (e.g., SuluFormBundle) are installed.
- Debug: Check if the field appears in php artisan sulu:form:fields:list. If not, verify the bundle’s service tags are registered.
Case Sensitivity in City Names:
- City names submitted via the form may not match database entries due to case differences (e.g., "berlin" vs. "Berlin").
- Fix: Normalize input in validation:
```
$request->validate([
    'city' => 'required|string|exists:cities,name',
]);
$normalizedCity = mb_strtolower($request->city);
```

Performance with Large City Lists:

Rendering a dropdown with thousands of cities can slow down the frontend.

Tip: Implement server-side filtering or lazy-loading:

// Use a library like Select2 with AJAX
$('.city-select').select2({
    ajax: {
        url: '/api/cities',
        dataType: 'json',
        delay: 250,
        data: function(params) {
            return { q: params.term };
        }
    }
});

Debugging

Log City Data: Add logging to inspect city data flow:

use Psr\Log\LoggerInterface;

class CitySelectHandler
{
    public function __construct(private LoggerInterface $logger) {}

    public function handleCitySelection(string $city): void
    {
        $this->logger->info('City selected', ['city' => $city]);
        // Process city...
    }
}

Check Bundle Events: The bundle may dispatch events (e.g., city.select). Listen for them in your code:

use Symfony\Component\EventDispatcher\EventDispatcherInterface;

$dispatcher->addListener('city.select', function($event) {
    $city = $event->getCity();
    // Handle event...
});

Database Mismatches: If cities submitted via the form don’t match database entries, verify:
- The name column in your cities table matches the submitted values.
- No typos in city names (e.g., "New York" vs. "New York City").

Extension Points

Custom City Data Source: Implement Eekes\Sulu\FormCitySelectBundle\Provider\CityProviderInterface to replace the default provider:

class DatabaseCityProvider implements CityProviderInterface
{
    public function getCities(): array
    {
        return City::query()->pluck('name')->toArray();
    }
}