Ti Ext Frontend Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require tastyigniter/ti-ext-frontend
   php artisan vendor:publish --provider="TastyIgniter\Frontend\FrontendServiceProvider"
   

   • Publishes migrations, config, and assets (Blade templates, JS/CSS).

2. Database Setup:

   php artisan migrate
   

   • Creates tables for sliders, banners, newsletter_subscribers, and contact_messages.

3. Basic Blade Integration:

   • Hero Slider (homepage):

     @component('frontend::slider', ['slides' => \App\Models\Slider::active()->get()])
     @endcomponent
     

   • Banner (promotional section):

     @component('frontend::banner', ['banner' => \App\Models\Banner::find(1)])
     @endcomponent
     

4. Form Setup:

   • Newsletter (MailChimp):

     @component('frontend::newsletter')
     @endcomponent
     

     • Configure .env:

       MAILCHIMP_API_KEY=your_key
       MAILCHIMP_LIST_ID=your_list_id
       

   • Contact Form (with reCAPTCHA):

     @component('frontend::contact-form')
     @endcomponent
     

     • Add Google reCAPTCHA site key to config/frontend.php:

       'recaptcha' => [
           'site_key' => 'your_site_key',
           'secret_key' => 'your_secret_key',
       ],
       

5. Admin Access:

   • Use TastyIgniter’s admin panel to manage sliders, banners, and form submissions via the Frontend extension menu.

Implementation Patterns

Core Workflows

1. Dynamic Slider Management

• Pattern: Use Eloquent to fetch and render sliders dynamically.

  // Controller
  public function showHomepage()
  {
      $slides = \App\Models\Slider::active()->orderBy('position')->get();
      return view('home', compact('slides'));
  }
  

  <!-- View -->
  @foreach($slides as $slide)
      <div class="slide">
          <img src="{{ $slide->image_url }}" alt="{{ $slide->title }}">
          <h2>{{ $slide->title }}</h2>
      </div>
  @endforeach
  

• Tip: Cache slider queries in the controller for performance:

  $slides = Cache::remember('homepage_slides', now()->addHours(1), function () {
      return \App\Models\Slider::active()->orderBy('position')->get();
  });
  

2. Banner Placement

• Pattern: Embed banners in Blade templates with conditional logic.

  @if($showPromoBanner)
      @component('frontend::banner', [
          'banner' => \App\Models\Banner::where('type', 'promo')->first()
      ])
      @endcomponent
  @endif
  

• Dynamic Banner Selection:

  // Route parameter or query string
  $banner = \App\Models\Banner::where('slug', request('banner_slug'))->firstOrFail();
  

3. Form Handling

• Newsletter Subscription:
  • Use the built-in MailChimp integration:

    // In a controller or service
    $subscriber = new \App\Models\NewsletterSubscriber([
        'email' => $request->email,
        'status' => 'subscribed'
    ]);
    $subscriber->subscribeToMailchimp(); // Uses package's MailchimpService
    

• Contact Form:
  • Extend the form handler to include custom logic:

    use TastyIgniter\Frontend\Services\ContactFormService;
    
    $contactService = new ContactFormService();
    $contactService->handle($request, function ($data) {
        // Custom logic (e.g., log to database, send Slack notification)
        \Log::info('New contact form submission', $data);
    });
    

4. reCAPTCHA Validation

• Pattern: Add validation to forms using Laravel’s built-in validator.

  $validator = Validator::make($request->all(), [
      'g-recaptcha-response' => 'required|captcha',
  ]);
  

• Config: Ensure config/frontend.php has reCAPTCHA keys:

  'recaptcha' => [
      'enabled' => env('RECAPTCHA_ENABLED', true),
      'site_key' => env('RECAPTCHA_SITE_KEY'),
      'secret_key' => env('RECAPTCHA_SECRET_KEY'),
  ],
  

5. Asset Management

• Custom CSS/JS: Override default assets by publishing and extending:

  php artisan vendor:publish --tag=frontend-assets --force
  

  • Modify published files in resources/assets/frontend/ and compile with Laravel Mix.

Integration Tips

Laravel-Specific Adaptations

1. Service Container Binding: If using Laravel’s service container, bind the package’s services:

   $this->app->bind(
       \TastyIgniter\Frontend\Services\MailchimpService::class,
       function ($app) {
           return new \TastyIgniter\Frontend\Services\MailchimpService(
               config('services.mailchimp.key'),
               config('services.mailchimp.list')
           );
       }
   );
   

2. Event Listeners: Extend form submission events:

   // Listen to newsletter subscription
   \App\Models\NewsletterSubscriber::created(function ($subscriber) {
       event(new \App\Events\NewsletterSubscribed($subscriber));
   });
   

3. Middleware: Protect admin routes for managing frontend components:

   Route::middleware(['auth', 'can:manage-frontend'])->group(function () {
       // Admin routes for sliders, banners, etc.
   });
   

Performance Optimizations

• Lazy-Load Sliders/Banners: Use JavaScript to load sliders/banners after page render:

  document.addEventListener('DOMContentLoaded', function() {
      const slider = document.getElementById('hero-slider');
      if (slider) {
          // Load slider content via AJAX or fetch
      }
  });
  

• Database Indexing: Add indexes to frequently queried fields:

  Schema::table('sliders', function (Blueprint $table) {
      $table->index('is_active');
      $table->index('position');
  });
  

Testing Patterns

• Unit Tests: Test form handlers and service logic:

  public function test_contact_form_submission()
  {
      $request = new \Illuminate\Http\Request([
          'name' => 'Test User',
          'email' => 'test@example.com',
          'message' => 'Hello!',
      ]);
  
      $this->mock(\TastyIgniter\Frontend\Services\Mailer::class)
           ->shouldReceive('send')
           ->once();
  
      $this->post('/contact', $request->all());
  }
  

• Feature Tests: Test Blade components in isolation:

  public function test_slider_component()
  {
      $slider = \App\Models\Slider::factory()->create(['is_active' => true]);
  
      $response = $this->get('/')
          ->assertSee($slider->title)
          ->assertSee($slider->image_url);
  }
  

Gotchas and Tips

Pitfalls

1. TastyIgniter Dependencies:

   • Issue: The package assumes TastyIgniter’s ORM, service container, and routing. Conflicts may arise with vanilla Laravel.
   • Fix: Override service bindings or create wrapper classes:

     class LaravelMailchimpService extends \TastyIgniter\Frontend\Services\MailchimpService
     {
         public function __construct()
         {
             parent::__construct(
                 config('services.mailchimp.key'),
                 config('services.mailchimp.list')
             );
         }
     }
     

2. reCAPTCHA Misconfiguration:

   • Issue: Forms may fail silently if reCAPTCHA keys are missing or invalid.
   • Fix: Validate keys in a service provider:

     if (!config('frontend.recaptcha.site_key') || !config('frontend.recaptcha.secret_key')) {
         throw new \RuntimeException('reCAPTCHA keys are not configured.');
     }
     

3. MailChimp Integration:

   • Issue: API calls may fail if MAILCHIMP_API_KEY or MAILCHIMP_LIST_ID are incorrect.
   • Fix: Use Laravel’s config/caching to avoid repeated API calls:

     $mailchimp = Cache::remember('mailchimp_service', now()->addHours(1), function () {
         return new \TastyIgn