Sf1 Embedder Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   "require": {
       "butterweed/sf1-embedder-bundle": "^1.0"
   }
   

   Run composer update.

2. Register the Bundle In AppKernel.php, add:

   new Butterweed\SF1EmbedderBundle\ButterweedSF1EmbedderBundle(),
   

3. Configure the Bundle Define a legacy app in config.yml:

   butterweed_sf1_embedder:
       map:
           main:
               prefix: /legacy  # Match requests starting with `/legacy`
               app: frontend    # Symfony1 app name (from `apps/` dir)
               path: "%kernel.root_dir%/../legacy"  # Path to legacy app root
   

4. Install the Symfony1 Plugin In your legacy app’s plugins/ directory, add the ButterweedSF1EmbedderPlugin (included in the bundle). Configure it in settings.yml:

   all:
       .plugins: [ButterweedSF1EmbedderPlugin]
   

5. Test the Embedder Access a legacy route (e.g., http://example.com/legacy). The request should now proxy to the Symfony1 app.

First Use Case: Incremental Migration

• Scenario: You have a Symfony1 app (/legacy) and want to migrate it to Symfony2 gradually.
• Action:
  1. Configure the embedder to handle /legacy/* routes.
  2. Update Symfony2 routes to handle new features (e.g., /api/*).
  3. Use the embedder for legacy URLs while developing new Symfony2 features.

Implementation Patterns

Workflow: Hybrid Routing

1. Symfony2 Routes First Define new routes in routing.yml for Symfony2 controllers:

   _symfony2:
       resource: "@AppBundle/Resources/config/routing.yml"
       prefix: /
   

2. Legacy Fallback Configure the embedder to catch unmatched routes:

   butterweed_sf1_embedder:
       map:
           legacy_fallback:
               prefix: /
               app: frontend
               path: "%kernel.root_dir%/../legacy"
               priority: -1  # Lowest priority (fallback)
   

3. Host-Specific Routing Route traffic based on hostnames:

   butterweed_sf1_embedder:
       map:
           admin_panel:
               prefix: /admin
               hosts: ["admin.example.com"]
               app: backend
               path: "%kernel.root_dir%/../admin-app"
   

Integration Tips

1. Debugging Tools

   • Both Symfony1 and Symfony2 debug toolbars will display simultaneously. Use Symfony1’s toolbar for legacy app insights.

2. User Session Sync The embedder auto-signs in sfUser and supports user switching. Ensure your Symfony1 app’s security.yml allows this:

   all:
       .security:
           user:
               is_anonymous: false
   

3. Static Assets Proxy static files (CSS/JS) from the legacy app by configuring the embedder’s prefix to match the legacy app’s asset paths.

4. Environment Matching The embedder auto-syncs SF_ENVIRONMENT and SF_DEBUG settings. Override in config.yml if needed:

   butterweed_sf1_embedder:
       env: dev  # Force environment (optional)
   

5. Multiple Legacy Apps Configure multiple apps in the map array:

   butterweed_sf1_embedder:
       map:
           app1:
               prefix: /app1
               app: app1
               path: "%kernel.root_dir%/../app1"
           app2:
               prefix: /app2
               app: app2
               path: "%kernel.root_dir%/../app2"
   

Gotchas and Tips

Pitfalls

1. Plugin Dependency

   • Issue: The embedder requires ButterweedSF1EmbedderPlugin in the legacy app. Forgetting to install it will cause 404 errors.
   • Fix: Verify the plugin is listed in settings.yml under .plugins.

2. Path Configuration

   • Issue: Incorrect path in the embedder config (e.g., wrong root directory) will break routing.
   • Fix: Use absolute paths (e.g., %kernel.root_dir%/../legacy) and validate the legacy app’s apps/ directory exists.

3. Route Conflicts

   • Issue: Symfony2 routes may conflict with legacy prefixes (e.g., /legacy vs. /legacy/*).
   • Fix: Use priority in the embedder config to control fallback order.

4. Session Handling

   • Issue: User sessions may not persist if Symfony1 and Symfony2 use different session handlers.
   • Fix: Configure both apps to use the same session storage (e.g., database or Redis).

5. Performance Overhead

   • Issue: The embedder adds runtime overhead for proxied requests.
   • Fix: Monitor performance and consider caching static responses or using a reverse proxy (e.g., Nginx) for legacy assets.

Debugging

1. Enable Verbose Logging Add to config.yml:

   butterweed_sf1_embedder:
       debug: true
   

   Logs will appear in Symfony2’s dev.log.

2. Check Embedder Events Listen for embedder events to debug routing:

   // src/AppBundle/EventListener/EmbedderListener.php
   class EmbedderListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'butterweed_sf1_embedder.route' => 'onRoute',
           ];
       }
   
       public function onRoute(GetResponseForControllerEvent $event) {
           // Dump $event->getController() to inspect routing
       }
   }
   

3. Symfony1 Debug Mode Ensure SF_DEBUG is true in the legacy app’s settings.yml to see detailed errors.

Extension Points

1. Custom Route Matching Extend the embedder’s router by implementing Butterweed\SF1EmbedderBundle\Router\RouterInterface:

   class CustomRouter implements RouterInterface {
       public function match(Request $request) {
           // Custom logic (e.g., regex matching)
           return $this->generate($request);
       }
   }
   

   Register it in services.yml:

   services:
       butterweed_sf1_embedder.router:
           class: AppBundle\Router\CustomRouter
           tags:
               - { name: butterweed_sf1_embedder.router }
   

2. Pre/Post-Request Hooks Use Symfony2’s event system to modify requests/responses before/after embedding:

   # config.yml
   butterweed_sf1_embedder:
       listeners:
           pre_request: [AppBundle\EventListener\PreEmbedListener]
           post_response: [AppBundle\EventListener\PostEmbedListener]
   

3. Override User Provider Customize auto-signin logic by extending the user provider:

   class CustomUserProvider extends \Butterweed\SF1EmbedderBundle\Security\User\SF1UserProvider {
       protected function loadUserByUsername($username) {
           // Custom logic (e.g., fetch from API)
       }
   }
   

   Register it in services.yml:

   services:
       butterweed_sf1_embedder.security.user_provider:
           class: AppBundle\Security\CustomUserProvider