Google Maps Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require cyberjaw/google-maps-bundle
   

   Ensure compatibility with Symfony ≥ 2.8.

2. Register Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2.8/3.x):

   CyberJaw\GoogleMapsBundle\GoogleMapsBundle::class => ['all' => true],
   

3. Configure API Key Add to config/packages/google_maps.yaml (Symfony 4+) or config.yml (Symfony 2.8/3.x):

   google_maps:
       api_key: 'YOUR_API_KEY'
   

4. Enable Twig Theme Add to config/packages/twig.yaml (Symfony 4+) or config.yml:

   twig:
       form_themes: ['GoogleMapsBundle:Form:google_maps_layout.html.twig']
   

5. Run Assets Install

   php bin/console assets:install
   

First Use Case

Basic Form Integration

// src/Form/YourFormType.php
use CyberJaw\GoogleMapsBundle\Form\Type\GoogleMapsType;

class YourFormType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('location', GoogleMapsType::class);
    }
}

Entity Mapping

// src/Entity/YourEntity.php
class YourEntity {
    private $latitude;
    private $longitude;
    private $city;
    private $address;

    // Add getters/setters
}

Implementation Patterns

Common Workflows

1. Dynamic Field Configuration Customize form types for latitude/longitude:

   $builder->add('location', GoogleMapsType::class, [
       'lat_type' => NumberType::class,
       'lng_type' => NumberType::class,
       'options' => ['attr' => ['class' => 'custom-class']]
   ]);
   

2. Data Binding Bind to entity properties:

   $form->handleRequest($request);
   if ($form->isSubmitted() && $form->isValid()) {
       $entity->setLatitude($form->get('location')->get('latitude')->getData());
       // Repeat for longitude, city, address
   }
   

3. Validation Add constraints to entity properties:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank
    * @Assert\Type("numeric")
    */
   private $latitude;
   

4. Twig Rendering Override default template:

   {% extends 'GoogleMapsBundle:Form:google_maps_layout.html.twig' %}
   {% block google_maps_widget %}
       {{ form_row(form) }}
       <div class="custom-marker">{{ form_widget(form.marker) }}</div>
   {% endblock %}
   

Integration Tips

• Symfony 4+: Use config/packages/ for bundle configuration.
• Asset Management: Ensure assets:install is run post-installation.
• API Key Security: Store keys in environment variables (e.g., .env).
• Caching: Cache API responses if using static maps or geocoding.

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Ensure your Google Maps API key has Maps JavaScript API enabled.
   • Avoid hardcoding keys; use environment variables:

     # .env
     GOOGLE_MAPS_API_KEY=your_key_here
     

     # config/packages/google_maps.yaml
     google_maps:
         api_key: '%env(GOOGLE_MAPS_API_KEY)%'
     

2. Form Theme Loading

   • If Twig templates fail to load, verify:
     • The form_themes path is correct.
     • The bundle is registered in bundles.php/AppKernel.php.
     • Assets are installed (assets:install).

3. Data Type Mismatches

   • Ensure entity properties match the form types (e.g., latitude as float/string).
   • Debug with:

     dump($form->get('location')->getData());
     

4. Deprecated Symfony Features

   • The bundle targets Symfony 2.8+. For Symfony 5+, test compatibility or fork the bundle.

Debugging

• Console Errors: Check for missing API keys or invalid form configurations.
• Twig Debug: Enable Twig debug mode to inspect template rendering:

  # config/packages/twig.yaml
  twig:
      debug: '%kernel.debug%'
  

• Network Requests: Verify API calls in browser DevTools (check for 403 errors if key is invalid).

Extension Points

1. Custom Form Types Extend GoogleMapsType for specialized use cases:

   class CustomGoogleMapsType extends GoogleMapsType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_option' => true,
           ]);
       }
   }
   

2. Template Overrides Override google_maps_layout.html.twig to modify rendering:

   {% extends 'GoogleMapsBundle:Form:google_maps_layout.html.twig' %}
   {% block google_maps_script %}
       {{ parent() }}
       <script>console.log("Custom script");</script>
   {% endblock %}
   

3. Event Listeners Hook into form events for dynamic behavior:

   $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $data = $event->getData();
       if ($data && $data->getCity()) {
           $event->getForm()->add('city_readonly', TextType::class, ['disabled' => true]);
       }
   });
   

4. Service Integration Inject the bundle’s services for advanced use:

   use CyberJaw\GoogleMapsBundle\Service\GoogleMapsService;
   
   class YourService {
       public function __construct(private GoogleMapsService $maps) {}
   }