Field Country Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/field-country
   

2. Register the Service Add this to config/packages/field.php (create if missing):

   use BaksDev\Field\Country\Choice\CountryFieldChoice;
   
   return static function (ContainerConfigurator $configurator) {
       $services = $configurator->services()
           ->defaults()
           ->autowire(true)
           ->autoconfigure(true);
   
       $services->set(CountryFieldChoice::class)
           ->tag('baks.fields.choice');
   };
   

3. First Use Case Use the field in a form builder (e.g., Symfony form or custom field system):

   $builder->add('country', CountryFieldChoice::class);
   

Implementation Patterns

Common Workflows

1. Basic Field Integration

   // In a form type or field definition
   $builder->add('country', CountryFieldChoice::class, [
       'label' => 'Select Country',
       'required' => true,
   ]);
   

2. Customizing Options Override default country list via dependency injection:

   $services->set(CountryFieldChoice::class)
       ->arg('$countries', ['US', 'CA', 'GB']) // Custom list
       ->tag('baks.fields.choice');
   

3. Template Overrides Place custom templates in templates/field-country/:

   • content.html.twig: Country list rendering.
   • template.html.twig: Wrapper structure.

4. Validation Use Symfony’s validation constraints:

   $builder->add('country', CountryFieldChoice::class, [
       'constraints' => [
           new NotBlank(),
           new Country(['message' => 'Invalid country.']),
       ],
   ]);
   

5. Dynamic Data Fetching Extend CountryFieldChoice to fetch countries from an API:

   class ApiCountryFieldChoice extends CountryFieldChoice {
       public function __construct(CountryApiClient $client) {
           $countries = $client->fetchCountries();
           parent::__construct($countries);
       }
   }
   

Gotchas and Tips

Pitfalls

1. PHP Version Requirement

   • Error: Class 'BaksDev\Field\Country\Choice\CountryFieldChoice' not found
   • Fix: Ensure PHP 8.4+ is used (package enforces this).

2. Missing Service Tag

   • Error: Field not registered in the system.
   • Fix: Verify ->tag('baks.fields.choice') is set in field.php.

3. Template Override Conflicts

   • Issue: Custom templates not loading.
   • Debug: Check file paths (templates/field-country/) and clear cache:

     php bin/console cache:clear
     

4. Country Code Validation

   • Gotcha: Default validation expects ISO 3166-1 alpha-2 codes (e.g., US, not United States).
   • Tip: Use Country constraint for validation:

     use BaksDev\Field\Country\Validator\Constraints\Country;
     

Debugging Tips

• Log Country List: Dump the country array in CountryFieldChoice constructor:

  public function __construct(array $countries = null) {
      $this->countries = $countries ?? [];
      \Log::debug('Loaded countries:', ['countries' => $this->countries]);
  }
  

• Check Service Dumping:

  php bin/console debug:container baks.fields.choice
  

Extension Points

1. Custom Country Source Extend CountryFieldChoice to load countries from a database or external service.

2. Localization Override content.html.twig to display country names in a specific language:

   {# Example: Russian names #}
   {% for code, name in countries %}
       <option value="{{ code }}">{{ name|translate({'domain': 'countries'}) }}</option>
   {% endfor %}
   

3. Grouped Countries Modify the template to group by region (e.g., Europe, Asia):

   {% for region, countries in countries|group_by('region') %}
       <optgroup label="{{ region }}">
           {% for code, name in countries %}
               <option value="{{ code }}">{{ name }}</option>
           {% endfor %}
       </optgroup>
   {% endfor %}