Terms Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require coopers-peele/terms-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       CoopersPeele\TermsBundle\CPTermsBundle::class => ['all' => true],
   ];
   

2. Database Setup Run migrations (check Resources/migrations/ for schema):

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Basic Terms Display Use the tos Twig extension to render terms:

   {{ tos('latest') }}
   

   Or fetch the latest terms programmatically:

   $terms = $this->get('cp_terms.manager')->getLatestTerms();
   

Implementation Patterns

Core Workflows

1. Managing Terms Versions

   • Use the admin interface (/admin/terms) to create/update versions.
   • Versioning is automatic; each update increments the version number.
   • Compare versions via:

     $diff = $this->get('cp_terms.manager')->getVersionDiff(1, 2);
     

2. User Agreement Tracking

   • Force agreement on signup via cp_terms.signup behavior (configure in config/packages/cp_terms.yaml):

     cp_terms:
         behaviors:
             signup: true
     

   • Check a user’s agreement status:

     $agreed = $this->get('cp_terms.manager')->userAgreed($user, $terms);
     

3. Frontend Integration

   • Display terms with version diffs:

     {% if tos('latest').hasChanges %}
         <div class="changes-highlight">
             {{ tos('latest').diffWithPrevious()|raw }}
         </div>
     {% endif %}
     

   • Add an "Accept Terms" button:

     $this->get('cp_terms.manager')->recordAgreement($user, $terms);
     

4. Notifications

   • Configure email notifications in config/packages/cp_terms.yaml:

     cp_terms:
         notifications:
             enabled: true
             template: 'emails/terms_updated.html.twig'
     

   • Trigger notifications when terms are updated (handled automatically by the bundle).

Laravel-Specific Adaptations

1. Service Container Binding Bind the manager to Laravel’s container in config/app.php:

   'bindings' => [
       // ...
       CoopersPeele\TermsBundle\Manager\TermsManagerInterface::class => CoopersPeele\TermsBundle\Manager\TermsManager::class,
   ],
   

2. Twig Integration Extend Laravel’s Twig environment in app/Providers/AppServiceProvider.php:

   public function boot()
   {
       $this->app['twig']->addExtension(new \CoopersPeele\TermsBundle\Twig\TermsExtension());
   }
   

3. Route Prefixes Override admin routes in routes/web.php:

   use CoopersPeele\TermsBundle\Resources\routing\admin_routes;
   
   admin_routes()->prefix('admin')->name('admin.');
   

4. Event Listeners Listen for term updates in Laravel’s event system:

   // app/Listeners/TermUpdatedListener.php
   public function handle(TermsUpdatedEvent $event)
   {
       // Custom logic (e.g., log updates, trigger analytics)
   }
   

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts

   • If using an existing terms table, drop it before running migrations or manually merge schemas.
   • Check Resources/migrations/ for the expected structure.

2. Twig Extension Not Loading

   • Ensure the Twig extension is registered after the bundle is loaded (e.g., in AppServiceProvider).
   • Clear the Twig cache if extensions disappear:

     php artisan view:clear
     

3. User Agreement Logic

   • The bundle assumes users are authenticated. For guest users, implement a cookie-based solution or extend the UserAgreement entity.
   • If using Laravel’s auth:api, ensure the User model matches the bundle’s expected structure (e.g., id, email).

4. Version Diff Rendering

   • The diffWithPrevious() method returns raw HTML. Sanitize output if rendering in untrusted contexts:

     {{ tos('latest').diffWithPrevious()|striptags }}
     

5. Notification Delays

   • Email notifications are sent after the terms are saved. For real-time updates, listen to the terms.updated event:

     event(new TermsUpdatedEvent($terms));
     

Debugging Tips

1. Enable Debug Mode Set debug: true in config/packages/cp_terms.yaml to log version changes and agreement records.

2. Check Database Records Verify entries in:

   • terms (terms content and versions)
   • user_agreements (user acceptance records)

3. Override Templates Customize Twig templates by copying from Resources/views/ to templates/cp_terms/.

4. Disable Behaviors Temporarily Set cp_terms.behaviors.signup: false to bypass signup enforcement during development.

Extension Points

1. Custom Validation Extend the Terms entity to add validation rules:

   use CoopersPeele\TermsBundle\Entity\Terms as BaseTerms;
   
   class CustomTerms extends BaseTerms
   {
       public function validate(\Symfony\Component\Validator\Constraint $constraint)
       {
           // Add custom rules
       }
   }
   

2. Additional Fields Add columns to the terms table via a custom migration and update the Terms entity:

   /**
    * @ORM\Column(type="boolean")
    */
   private $isActive;
   

3. Custom Notifications Override the notification service:

   cp_terms:
       notifications:
           service: 'app.custom_notification_service'
   

4. API Integration Create a custom controller to expose terms via API:

   use CoopersPeele\TermsBundle\Manager\TermsManagerInterface;
   
   class TermsApiController extends Controller
   {
       public function __construct(private TermsManagerInterface $manager) {}
   
       public function getLatestTerms()
       {
           return response()->json($this->manager->getLatestTerms());
       }
   }