Remote Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cravler/remote-bundle:@dev
   

   Ensure you’re using @dev for the latest features (no stable release yet).

2. Enable the Bundle Add to app/AppKernel.php:

   new Cravler\RemoteBundle\CravlerRemoteBundle(),
   

3. Routing Include in app/config/routing.yml:

   cravler_remote:
       resource: "@CravlerRemoteBundle/Resources/config/routing.xml"
   

4. Node Dependencies Install frontend assets (critical for WebSocket/real-time features):

   npm install --prefix vendor/cravler/remote-bundle/Cravler/RemoteBundle/Resources/nodejs
   

5. First Use Case Configure ports/secrets in app/config/config.yml:

   cravler_remote:
       app_port: 8080          # Local app port
       remote_port: 8081       # Remote server port
       server_port: 8082       # Admin/server port
       secret: "YourSecureToken123"  # Change this!
   

   Start services (Ubuntu example):

   app/console cravler:remote:ubuntu:upstart server
   app/console cravler:remote:ubuntu:upstart app
   

Implementation Patterns

Core Workflows

1. Real-Time Communication

   • Use the bundle’s WebSocket endpoints (defined in routing.xml) to sync data between local/remote instances.
   • Example: Broadcast user actions (e.g., chat messages) via cravler_remote_socket route.

2. Service Isolation

   • App Port (8080): Host your Laravel frontend.
   • Remote Port (8081): Expose APIs for remote clients (e.g., mobile apps).
   • Server Port (8082): Admin/API for managing remote connections.

3. Authentication

   • Integrate with user_provider (e.g., Symfony’s security system) to validate remote requests:

     cravler_remote:
         user_provider: security.user.provider.custom
     

4. Data Sync

   • Use the CravlerRemoteBundle\Event\RemoteSyncEvent to listen for data changes:

     // src/EventListener/RemoteSyncListener.php
     public function onRemoteSync(RemoteSyncEvent $event) {
         $data = $event->getData();
         // Process/sync $data to remote
     }
     

     Register in services.yml:

     services:
         cravler.remote.sync_listener:
             class: AppBundle\EventListener\RemoteSyncListener
             tags:
                 - { name: kernel.event_listener, event: cravler.remote.sync, method: onRemoteSync }
     

5. Frontend Integration

   • Include the bundle’s JS assets (e.g., vendor/cravler/remote-bundle/Cravler/RemoteBundle/Resources/nodejs/dist/remote.js) to handle WebSocket connections:

     const socket = new WebSocket(`ws://localhost:8081/remote_socket`);
     socket.onmessage = (event) => {
         const data = JSON.parse(event.data);
         // Handle remote data
     };
     

Gotchas and Tips

Pitfalls

1. Port Conflicts

   • Ensure app_port, remote_port, and server_port are unused. Use netstat -tulnp to check.
   • Fix: Change ports in config.yml or kill conflicting processes.

2. Node Dependencies

   • The bundle relies on Node.js for WebSocket handling. If npm install fails:
     • Verify Node.js (≥v12) and npm are installed.
     • Reinstall dependencies after updating the bundle.

3. Secret Token

   • The default secret (ThisTokenIsNotSoSecretChangeIt) is insecure. Always override it in config.yml.
   • Tip: Use environment variables:

     secret: "%env(REMOTE_BUNDLE_SECRET)%"
     

4. Ubuntu Upstart

   • The cravler:remote:ubuntu:upstart commands generate init scripts for service management.
   • Gotcha: If using non-Ubuntu systems, manually configure systemd or supervisor instead.

5. Event Dispatching

   • Events like RemoteSyncEvent must be manually dispatched. Forgetting to trigger them breaks sync:

     // Wrong: Event won't fire
     $event = new RemoteSyncEvent($data);
     
     // Correct: Dispatch via EventDispatcher
     $this->get('event_dispatcher')->dispatch(
         'cravler.remote.sync',
         $event
     );
     

Debugging

1. WebSocket Issues

   • Check browser console for connection errors (e.g., WebSocket connection to 'ws://...' failed).
   • Debug: Enable Symfony’s WebSocket logger:

     # app/config/config.yml
     monolog:
         handlers:
             cravler_remote:
                 type: stream
                 path: "%kernel.logs_dir%/cravler_remote.log"
                 level: debug
     

2. Port Binding Failures

   • Run app/console debug:config cravler_remote to verify config values.
   • Test ports manually:

     curl http://localhost:8081/remote_health_check
     

Extension Points

1. Custom User Provider

   • Extend Cravler\RemoteBundle\Security\User\RemoteUserProvider to integrate with your auth system:

     class CustomRemoteUserProvider extends RemoteUserProvider {
         public function loadUserByUsername($username) {
             // Custom logic (e.g., API call)
         }
     }
     

     Register in config.yml:

     cravler_remote:
         user_provider: app.custom.remote_user_provider
     

2. Custom Events

   • Extend the bundle’s event system by creating new events (e.g., RemoteDataTransformEvent) and listeners.

3. Frontend Customization

   • Override the bundle’s JS/CSS by copying Resources/nodejs/ to your project and updating paths in routing.xml.

4. Remote API Endpoints

   • Add custom routes to routing.xml under <cravler_remote> to expose additional remote APIs.