Acceptance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atournayre/acceptance-bundle
   

2. Enable the Bundle Add to config/bundles.php:

   return [
       Atournayre\AcceptanceBundle\AtournayreAcceptanceBundle::class => ['all' => true],
   ];
   

3. Configure via .env (Recommended) Add to your .env file:

   ACCEPTANCE_IS_ENABLED=true
   ACCEPTANCE_START_DATETIME=2024-01-01 00:00:00
   ACCEPTANCE_END_DATETIME=2024-01-07 23:59:59
   

4. Link Config in services.yaml

   parameters:
       atournayre_acceptance.is_enabled: '%env(ACCEPTANCE_IS_ENABLED)%'
       atournayre_acceptance.start_date_time: '%env(ACCEPTANCE_START_DATETIME)%'
       atournayre_acceptance.end_date_time: '%env(ACCEPTANCE_END_DATETIME)%'
   

5. First Use Case: Check Acceptance Status Inject the service in a controller or service:

   use Atournayre\AcceptanceBundle\Service\AcceptanceChecker;
   
   public function __construct(private AcceptanceChecker $acceptanceChecker) {}
   
   public function index()
   {
       if ($this->acceptanceChecker->isAcceptanceActive()) {
           return new Response('Acceptance environment is active!');
       }
       return new Response('Acceptance environment is inactive.');
   }
   

Implementation Patterns

Core Workflow: Environment Activation

1. Define Acceptance Period Use .env or parameters.yml to set start_date_time and end_date_time. Example:

   ACCEPTANCE_START_DATETIME=2024-05-01
   ACCEPTANCE_END_DATETIME=2024-05-15
   

2. Toggle Acceptance Mode Enable/disable via:

   ACCEPTANCE_IS_ENABLED=true  # Enable for testing
   ACCEPTANCE_IS_ENABLED=false # Disable in production
   

3. Check Status Programmatically Use the AcceptanceChecker service in:

   • Controllers: Redirect users based on acceptance status.

     if (!$this->acceptanceChecker->isAcceptanceActive()) {
         return $this->redirectToRoute('home');
     }
     

   • Middleware: Restrict access to acceptance-only routes.

     public function handle(Request $request, Closure $next)
     {
         if (!$this->acceptanceChecker->isAcceptanceActive()) {
             throw new AccessDeniedException('Acceptance environment is disabled.');
         }
         return $next($request);
     }
     

   • Services: Validate acceptance before processing requests.

     if (!$this->acceptanceChecker->isAcceptanceActive()) {
         throw new \RuntimeException('Acceptance mode is not active.');
     }
     

4. Dynamic Configuration Override dates via environment variables or config files for different environments (e.g., env.local.php for local testing).

Integration Tips

1. Symfony Flex Compatibility Ensure config/services.yaml is properly linked to .env variables. Use:

   parameters:
       atournayre_acceptance.is_enabled: '%env(bool:ACCEPTANCE_IS_ENABLED)%'
   

2. Custom Templates Override default templates (e.g., for custom acceptance banners) by copying from:

   vendor/atournayre/acceptance-bundle/Resources/views/
   

   to:

   templates/bundles/AtournayreAcceptanceBundle/
   

3. Event-Based Activation Trigger actions when acceptance starts/ends using Symfony events (e.g., kernel.request listener):

   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($this->acceptanceChecker->isAcceptanceActive()) {
           // Log or notify when acceptance starts
       }
   }
   

4. Database Integration Store acceptance dates in a database table (e.g., acceptance_periods) and fetch them dynamically:

   $startDate = $this->acceptanceRepository->findStartDate();
   $this->acceptanceChecker->setStartDateTime($startDate);
   

Gotchas and Tips

Pitfalls

1. Time Zone Sensitivity Dates in .env are parsed as UTC. Ensure your application’s time zone (e.g., APP_TIMEZONE in .env) matches expectations:

   APP_TIMEZONE=Europe/Paris
   

2. Date Format Strictness The bundle expects strict date formats. Invalid formats (e.g., "2024/01/01") will throw exceptions. Use:

   • YYYY-MM-DD (e.g., "2024-01-01")
   • YYYY-MM-DD HH:MM:SS (e.g., "2024-01-01 12:00:00")

3. Caching Issues If using Symfony’s cache, clear it after changing .env or parameters.yml:

   php bin/console cache:clear
   

4. Bundle Disabling in Production Forgetting to disable the bundle (ACCEPTANCE_IS_ENABLED=false) in production can expose acceptance environments unintentionally.

Debugging

1. Check Current Status Add a debug route to verify acceptance status:

   use Symfony\Component\HttpFoundation\Response;
   
   public function debugAcceptance(AcceptanceChecker $checker)
   {
       return new Response(
           'Acceptance Active: ' . ($checker->isAcceptanceActive() ? 'Yes' : 'No') .
           '<br>Start: ' . $checker->getStartDateTime() .
           '<br>End: ' . $checker->getEndDateTime()
       );
   }
   

2. Log Acceptance Events Extend the AcceptanceChecker to log transitions:

   public function isAcceptanceActive(): bool
   {
       $active = parent::isAcceptanceActive();
       $this->logger->info('Acceptance status: ' . ($active ? 'ACTIVE' : 'INACTIVE'));
       return $active;
   }
   

Extension Points

1. Custom Validation Logic Extend the AcceptanceChecker to add business rules (e.g., user-specific acceptance periods):

   class CustomAcceptanceChecker extends AcceptanceChecker
   {
       public function isUserAcceptanceActive(User $user): bool
       {
           return $this->isAcceptanceActive() && $user->hasAcceptanceAccess();
       }
   }
   

2. Database-Backed Periods Replace hardcoded dates with dynamic queries:

   public function getStartDateTime(): \DateTimeInterface
   {
       $date = $this->acceptanceRepository->findStartDate();
       return new \DateTime($date);
   }
   

3. Environment-Specific Config Use env.local.php to override dates per environment:

   return [
       'ACCEPTANCE_START_DATETIME' => '2024-06-01', // Local override
   ];
   

4. Event Dispatching Dispatch events when acceptance starts/ends:

   public function isAcceptanceActive(): bool
   {
       $active = parent::isAcceptanceActive();
       if ($active) {
           $this->eventDispatcher->dispatch(new AcceptanceStartedEvent());
       }
       return $active;
   }