Veritas Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dbstudios/veritas-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DbStudios\VeritasBundle\DbStudiosVeritasBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console veritas:install
   

   Edit config/packages/veritas.yaml to match your JWT provider (e.g., firebase, auth0).

3. First Use Case Generate a token in a controller:

   use DbStudios\VeritasBundle\Veritas;
   
   public function generateToken(Veritas $veritas): Response
   {
       $token = $veritas->generateToken(['user_id' => 123]);
       return new JsonResponse(['token' => $token]);
   }
   

Implementation Patterns

Common Workflows

1. Token Generation

   // Basic payload
   $token = $veritas->generateToken(['uid' => 'user123']);
   
   // With custom claims
   $token = $veritas->generateToken([
       'uid' => 'user123',
       'custom_claim' => 'value',
   ], ['exp' => time() + 3600]); // Override defaults
   

2. Token Validation

   public function validateToken(Veritas $veritas, Request $request): Response
   {
       $token = $request->headers->get('Authorization');
       $claims = $veritas->validateToken($token);
   
       if (!$claims) {
           return new Response('Invalid token', 401);
       }
       return new JsonResponse($claims);
   }
   

3. Middleware Integration

   // src/Kernel.php
   protected function build(Request $request): Response
   {
       $this->addVeritasMiddleware(); // Auto-injected by bundle
       return parent::build($request);
   }
   

4. Custom Providers Extend DbStudios\VeritasBundle\Provider\AbstractProvider for non-standard JWT providers.

Integration Tips

• Symfony Security Component: Use veritas.security.authenticator for guard-based auth.
• API Platform: Annotate DTOs with @Security to restrict access:

  use ApiPlatform\Core\Annotation\Security;
  #[Security("is_granted('ROLE_USER')")]
  

Gotchas and Tips

Pitfalls

1. Token Expiry

   • Default exp is 1 hour. Override in veritas.yaml:

     veritas:
         default_claims:
             exp: 86400 # 24 hours
     

   • Debugging: Use veritas:debug command to inspect token claims.

2. Provider Mismatch

   • Ensure provider in veritas.yaml matches your JWT issuer (e.g., firebase vs. auth0).
   • Fix: Re-run veritas:install or manually update config/packages/veritas.yaml.

3. CORS Headers

   • If using API tokens, ensure Access-Control-Expose-Headers includes Authorization in your CORS config.

Debugging

• Command-Line Tools:

  # Generate a token with debug info
  php bin/console veritas:generate --payload='{"uid":"test"}' --debug
  
  # Validate a token
  php bin/console veritas:validate "your.token.here"
  

• Logging: Enable monolog in veritas.yaml for detailed token events:

  veritas:
      logging: true
  

Extension Points

1. Custom Claims Add a subscriber to modify payloads:

   use DbStudios\VeritasBundle\Event\TokenGenerateEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class CustomClaimsSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               TokenGenerateEvent::NAME => 'onTokenGenerate',
           ];
       }
   
       public function onTokenGenerate(TokenGenerateEvent $event)
       {
           $event->setPayload(array_merge($event->getPayload(), ['app_version' => '1.0']));
       }
   }
   

2. Token Storage Override DbStudios\VeritasBundle\Storage\TokenStorageInterface for custom storage (e.g., Redis).

3. Provider-Specific Logic Extend AbstractProvider to handle non-standard JWT formats or claims.