Php Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require splash/php-bundle
   

   Add the bundle to config/bundles.php in Symfony:

   return [
       // ...
       Splash\Bundle\CoreBundle\SplashCoreBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Authentication: Splash provides OAuth2 integration. Start with Splash\CoreBundle\Security\Authenticator\OAuth2Authenticator in your security.yaml:

     firewalls:
         main:
             oauth2:
                 provider: splash_oauth_provider
     

3. Configuration:

   • Publish default config:

     php bin/console splash:install
     

   • Update config/packages/splash_core.yaml with your OAuth2 credentials (client ID, secret, etc.).

4. Quick Test:

   • Run the OAuth2 login flow via /connect/splash endpoint.

Implementation Patterns

Core Workflows

1. OAuth2 Integration:

   • Provider Setup: Extend Splash\CoreBundle\Security\OAuth2\Provider\AbstractProvider for custom providers.
   • User Mapping: Implement Splash\CoreBundle\Security\User\UserMapperInterface to sync Splash users with your Symfony users.

     class SplashUserMapper implements UserMapperInterface {
         public function mapUser(array $data): UserInterface {
             return new User($data['email'], $data['password']);
         }
     }
     

2. API Client:

   • Use Splash\CoreBundle\Client\SplashClient for API calls:

     $client = $this->container->get('splash.client');
     $response = $client->get('/api/v1/users');
     

3. Event Listeners:

   • Subscribe to Splash events (e.g., splash.user.created) via Symfony’s event dispatcher:

     $dispatcher->addListener('splash.user.created', function (UserEvent $event) {
         // Handle user creation logic
     });
     

4. Command-Line Tools:

   • Use built-in commands for syncing data:

     php bin/console splash:sync:users
     

Integration Tips

• Symfony Forms: Bind Splash user data to Symfony forms using Splash\CoreBundle\Form\Type\UserType.
• Twig Extensions: Access Splash data in templates via splash Twig extension:

  {{ splash.user.displayName }}
  

• Doctrine Entities: Sync Splash entities with Doctrine by extending Splash\CoreBundle\Doctrine\SplashEntity.

Gotchas and Tips

Common Pitfalls

1. Deprecated Methods:

   • The package was last updated in 2020. Check for Symfony 5/6 compatibility issues (e.g., EventDispatcherInterface changes).
   • Workaround: Override deprecated services in config/services.yaml:

     Splash\CoreBundle\:
         resource: '../vendor/splash/php-bundle/src/'
         exclude: '../vendor/splash/php-bundle/src/{Entity,DependencyInjection}'
     

2. OAuth2 Flow:

   • Ensure redirect_uri in Splash dashboard matches your Symfony login_path (e.g., /connect/splash/check).
   • Debugging: Enable debug mode in splash_core.yaml:

     splash_core:
         debug: true
     

3. User Sync:

   • Default UserMapper may not handle all Splash fields. Extend it to map custom attributes:

     public function mapUser(array $data): UserInterface {
         $user = new User();
         $user->setEmail($data['email'] ?? '');
         $user->setCustomField($data['custom_field'] ?? null); // Add missing fields
         return $user;
     }
     

4. Caching:

   • Splash API responses are cached by default. Clear cache after manual syncs:

     php bin/console cache:clear
     

Extension Points

1. Custom Providers:

   • Extend AbstractProvider to support non-OAuth2 auth (e.g., API keys):

     class ApiKeyProvider extends AbstractProvider {
         public function getCredentials(): array {
             return ['api_key' => $this->request->headers->get('X-API-KEY')];
         }
     }
     

2. Webhooks:

   • Listen for Splash webhook events by implementing Splash\CoreBundle\Event\WebhookListenerInterface:

     class CustomWebhookListener implements WebhookListenerInterface {
         public function onWebhookReceived(WebhookEvent $event) {
             // Handle webhook payload
         }
     }
     

3. Testing:

   • Mock SplashClient in tests:

     $client = $this->createMock(SplashClient::class);
     $client->method('get')->willReturn(['data' => 'test']);
     $this->container->set('splash.client', $client);
     

Configuration Quirks

• Environment Variables:
  • Splash credentials should not be hardcoded. Use Symfony’s %env% in splash_core.yaml:

    splash_core:
        client_id: '%env(SPLASH_CLIENT_ID)%'
        client_secret: '%env(SPLASH_CLIENT_SECRET)%'
    

• Rate Limiting:
  • Splash API has rate limits. Implement exponential backoff in custom clients:

    use GuzzleHttp\Exception\RequestException;
    try {
        $response = $client->get('/api/v1/users');
    } catch (RequestException $e) {
        if ($e->getCode() === 429) {
            sleep(2); // Retry after delay
        }
    }