Giltza Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require amorebietakoudala/giltza-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Amorebietakoudala\GiltzaBundle\GiltzaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console giltza:install
   

   Update config/packages/giltza.yaml with your Giltza API credentials (client ID, secret, etc.).

3. First Use Case: Authentication Use the GiltzaAuthenticator in your Symfony security configuration (config/packages/security.yaml):

   security:
       firewalls:
           main:
               oauth:
                   resource_owners:
                       giltza: ~
                   login_path: /login
                   use_forward: false
   

4. Quick Test Run the OAuth flow manually:

   php bin/console debug:oauth:authorize giltza
   

Implementation Patterns

Workflows

1. OAuth Flow Integration

   • User Login: Redirect users to Giltza for authentication via the giltza/login route.
   • Callback Handling: The bundle auto-handles the OAuth callback at /connect/giltza/check.
   • User Association: Link Giltza accounts to your Symfony users via the UserEntity trait:

     use Amorebietakoudala\GiltzaBundle\Model\UserInterface;
     
     class AppUser implements UserInterface {
         // ...
     }
     

2. API Access Use the GiltzaClient service to fetch user data after authentication:

   use Amorebietakoudala\GiltzaBundle\Client\GiltzaClient;
   
   class MyController {
       public function __construct(private GiltzaClient $giltzaClient) {}
   
       public function profile() {
           $userData = $this->giltzaClient->getUser();
           // ...
       }
   }
   

3. Event Listeners Subscribe to Giltza events (e.g., GiltzaAuthSuccessEvent) to extend logic:

   # config/services.yaml
   services:
       App\EventListener\GiltzaListener:
           tags:
               - { name: kernel.event_listener, event: giltza.auth.success, method: onAuthSuccess }
   

Integration Tips

• Symfony Forms: Use the GiltzaType form field for manual OAuth login forms:

  use Amorebietakoudala\GiltzaBundle\Form\Type\GiltzaType;
  
  $builder->add('giltza_login', GiltzaType::class);
  

• Custom Claims: Extend the GiltzaUserProvider to map Giltza claims to your user model:

  class CustomGiltzaUserProvider extends GiltzaUserProvider {
      protected function getUsernameFromUserData(array $data): string {
          return $data['custom_claim'] ?? parent::getUsernameFromUserData($data);
      }
  }
  

• Caching: Cache Giltza API responses with Symfony’s cache system:

  $this->giltzaClient->setCache($cacheItemPool);
  

Gotchas and Tips

Pitfalls

1. Propietary License

   • The bundle is proprietary-licensed. Ensure compliance with Giltza’s terms before production use.

2. PHP 8.2+ Requirement

   • If using older PHP, upgrade or fork the bundle to drop the version constraint.

3. Missing Documentation

   • The bundle lacks detailed docs. Key classes (GiltzaClient, GiltzaAuthenticator) may need reverse-engineering via tests or source.

4. Event System Quirks

   • Events like GiltzaAuthSuccessEvent may not be dispatched if the user provider fails silently. Add error handling:

     try {
         $user = $this->giltzaUserProvider->loadUserByOAuthToken($token);
     } catch (\Exception $e) {
         $this->eventDispatcher->dispatch(new GiltzaAuthFailureEvent($e));
     }
     

5. CSRF on Callback

   • The /connect/giltza/check endpoint may fail if CSRF protection is enabled. Exclude it in security.yaml:

     security:
         access_control:
             - { path: ^/connect/giltza/check, roles: PUBLIC_ACCESS }
     

Debugging

• Enable Debug Mode Set debug: true in giltza.yaml to log OAuth tokens and API responses:

  giltza:
      debug: true
  

• Token Validation If API calls fail, verify the access token isn’t expired. Refresh it via:

  $this->giltzaClient->refreshToken();
  

• Symfony Cache Issues Clear the cache after config changes:

  php bin/console cache:clear
  

Extension Points

1. Custom Providers Override GiltzaUserProvider to implement custom user loading logic:

   class CustomProvider extends GiltzaUserProvider {
       public function loadUserByOAuthToken($token) {
           // Custom logic
       }
   }
   

   Register it in services.yaml:

   services:
       Amorebietakoudala\GiltzaBundle\Security\User\GiltzaUserProvider:
           alias: App\Security\User\CustomProvider
   

2. API Client Extensions Extend GiltzaClient to add custom endpoints:

   class CustomGiltzaClient extends GiltzaClient {
       public function getCustomData() {
           return $this->fetch('https://api.giltza.com/custom');
       }
   }
   

3. Twig Integration Pass Giltza user data to Twig:

   $this->get('twig')->addGlobal('giltza_user', $this->giltzaClient->getUser());