Cowegis Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Run:

   composer require cowegis/cowegis-client-bundle
   

   Then enable the bundle in config/bundles.php:

   return [
       // ...
       Cowegis\ClientBundle\CowegisClientBundle::class => ['all' => true],
   ];
   

2. Publish Assets Dump assets to integrate the Cowegis JavaScript client:

   php bin/console assets:install public
   npm install && npm run build  # If using Webpack Encore
   

3. First Use Case: Embedding a Map Add the Cowegis client to your Symfony template (e.g., templates/base.html.twig):

   {{ encore_entry_script_tags('app') }}  {# Ensure Webpack Encore is configured #}
   <script src="{{ asset('bundles/cowegis/client/cowegis.js') }}"></script>
   

   Initialize the client in a Twig template or JavaScript file:

   const cowegis = new Cowegis({
       apiKey: 'YOUR_API_KEY',  // Replace with your Cowegis API key
       container: document.getElementById('map-container')
   });
   

Implementation Patterns

Workflow: Integrating Cowegis with Symfony

1. API Key Management Store the Cowegis API key in Symfony’s .env:

   COWEGIS_API_KEY=your_api_key_here
   

   Access it in Twig or PHP:

   <script>
       const apiKey = "{{ env('COWEGIS_API_KEY') }}";
   </script>
   

2. Dynamic Configuration Pass runtime data (e.g., map center, layers) via Symfony’s Twig:

   <script>
       const config = {
           center: {{ coordinates|json_encode }},
           layers: {{ layers|json_encode }}
       };
       const cowegis = new Cowegis({ ...config, apiKey });
   </script>
   

3. Event Handling Use Symfony’s event system to trigger Cowegis actions (e.g., after a form submission):

   // src/EventListener/CowegisListener.php
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class CowegisListener {
       public function onKernelRequest(RequestEvent $event) {
           if ($event->isMainRequest()) {
               // Dispatch a JavaScript event to Cowegis
               $event->getRequest()->attributes->set('cowegis_event', 'map:update');
           }
       }
   }
   

   Listen in JavaScript:

   document.addEventListener('DOMContentLoaded', () => {
       if (window.cowegisEvent === 'map:update') {
           cowegis.updateMap();
       }
   });
   

4. Asset Optimization Configure Webpack Encore to bundle Cowegis with your app:

   // webpack.config.js
   Encore
       .addEntry('app', './assets/app.js')
       .copyFiles({
           from: './vendor/cowegis/client/dist',
           to: 'bundles/cowegis/client/[path][name].[hash].[ext]'
       });
   

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Ensure assets:install is run after installation. Cowegis JS/CSS files are copied to public/bundles/cowegis/client/.
   • If using Symfony Flex, verify the public directory is writable.

2. API Key Exposure

   • Avoid hardcoding API keys in templates. Use .env and Twig’s env() function.
   • For production, consider using Symfony’s ParameterBag to inject the key into services.

3. JavaScript Conflicts

   • Cowegis may rely on global variables (e.g., Cowegis). Use Webpack’s ProvidePlugin to avoid conflicts:

     // webpack.config.js
     Encore.configureBabelPresetEnv((config) => {
         config.useBuiltIns = 'usage';
         config.corejs = 3;
     });
     Encore.enableSingleRuntimeChunk();
     

4. Debugging

   • Check the browser’s Network tab for failed asset loads (e.g., cowegis.js 404).
   • Use {{ dump(env('COWEGIS_API_KEY')) }} in Twig to verify environment variables.

Tips

1. Extension Points

   • Override Cowegis’s default behavior by extending its JavaScript class:

     class CustomCowegis extends Cowegis {
         constructor(config) {
             super(config);
             this.addCustomLayer();
         }
     }
     

   • Load the custom class after Cowegis’s script:

     <script src="{{ asset('bundles/cowegis/client/cowegis.js') }}"></script>
     <script src="{{ asset('js/custom-cowegis.js') }}"></script>
     

2. Symfony UX Integration

   • Pair with Symfony UX for reactive components:

     // src/Controller/MapController.php
     use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
     
     #[AsLiveComponent('map')]
     class MapController extends AbstractController {
         public function __invoke(Request $request) {
             return $this->render('map/index.html.twig');
         }
     }
     

   • Update Cowegis dynamically via Symfony UX events.

3. Testing

   • Mock Cowegis in PHPUnit by overriding the global object:

     // tests/assets/mock-cowegis.js
     window.Cowegis = jest.fn().mockImplementation(() => ({
         updateMap: jest.fn()
     }));
     

   • Use Symfony’s KernelBrowser to test interactions:

     $client = static::createClient();
     $client->enableProfiler();
     $client->request('GET', '/map');