Ucsf Panichd Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run:

   composer require jschlies/panichd
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="PanicHD\PanicHDServiceProvider" --tag="config"
   php artisan vendor:publish --provider="PanicHD\PanicHDServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="PanicHD\PanicHDServiceProvider" --tag="public"
   

2. Run Migrations

   php artisan migrate
   

3. Configure Routes Add the package route to your routes/web.php:

   Route::prefix('PanicHD')->group(function () {
       require __DIR__.'/vendor/jschlies/panichd/routes/web.php';
   });
   

   (Modify the prefix if needed.)

4. First Use Case Visit /PanicHD in your browser. Use the web installer to set up:

   • Default categories, statuses, and priorities.
   • Email configurations for notifications.
   • Admin users.

Where to Look First

• Documentation: PanicHD Wiki (features, API, and workflows).
• Demo Data: Run php artisan panic:demo to populate sample tickets/categories for testing.
• Config File: config/panichd.php (customize routes, email templates, and default settings).
• Blade Templates: resources/views/vendor/panichd/ (override default views if needed).

Implementation Patterns

Core Workflows

1. Ticket Creation (Form-Based)

• Use the built-in form at /PanicHD/tickets/create.
• Customization: Extend the form via resources/views/vendor/panichd/tickets/create.blade.php.
• Validation: Override validation rules in app/Providers/PanicHDServiceProvider.php:

  public function boot()
  {
      PanicHD::extend(function ($panichd) {
          $panichd->validationRules = [
              'title' => 'required|max:255',
              'description' => 'required|min:10',
              // Custom rules...
          ];
      });
  }
  

2. File Attachments

• Attach files to tickets via the form (supports PDFs, images, etc.).
• Custom Storage: Configure storage disk in config/panichd.php:

  'attachments_disk' => 's3', // Default: 'public'
  

3. Tags and Categorization

• Assign tags/categories during ticket creation.
• Dynamic Tags: Add tags via seeder or admin panel.
• Filtering: Use the search/filter UI at /PanicHD/tickets.

4. Email Notifications

• Notifications trigger on ticket creation/status changes.
• Custom Templates: Override email templates in resources/views/vendor/panichd/emails/.
• Recipients: Configure default recipients in config/panichd.php:

  'notifications' => [
      'ticket_created' => ['admin@example.com'],
  ],
  

5. Scheduling

• Set due dates for tickets via the form.
• Reminders: Configure reminder emails in config/panichd.php:

  'reminders' => [
      'enabled' => true,
      'days_before_due' => 1,
  ],
  

Integration Tips

Laravel Ecosystem

• Authentication: PanicHD integrates with Laravel’s auth. Restrict access via middleware:

  Route::middleware(['auth', 'admin'])->group(function () {
      // Admin-only routes
  });
  

• Events: Listen to PanicHD events (e.g., ticket.created):

  PanicHD::listen('ticket.created', function ($ticket) {
      Log::info("New ticket #{$ticket->id} created.");
  });
  

• API Access: Expose endpoints via Laravel API resources:

  Route::apiResource('panichd/tickets', \PanicHD\Http\Controllers\TicketController::class);
  

Frontend Customization

• Blade Overrides: Copy default views to resources/views/vendor/panichd/ and modify.
• CSS/JS: Publish assets and extend:

  php artisan vendor:publish --tag="public" --provider="PanicHD\PanicHDServiceProvider"
  

  Add custom styles to public/vendor/panichd/css/panichd.css.

Backend Extensions

• Custom Fields: Extend the ticket model:

  class Ticket extends \PanicHD\Models\Ticket
  {
      protected $casts = [
          'custom_field' => 'array',
      ];
  }
  

• Database: Add columns via migrations (e.g., php artisan make:migration add_custom_field_to_tickets_table).

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Default route /PanicHD may clash with existing routes. Fix: Change the prefix in routes/web.php or use a subdomain.
   • Debug: Run php artisan route:list to check conflicts.

2. Email Configuration

   • Notifications fail if MAIL_DRIVER is misconfigured. Fix: Verify .env and test with php artisan panic:test-email.

3. File Upload Limits

   • Default upload size is 2MB. Fix: Adjust in config/panichd.php:

     'max_file_size' => '10M', // In MB
     

4. Demo Data Overwrite

   • Running php artisan panic:demo multiple times may duplicate data. Fix: Clear the database or use --force carefully.

5. Translation Issues

   • Missing translations appear as keys (e.g., {{ __('panichd::ticket.title') }}). Fix:
     • Publish translations: php artisan vendor:publish --tag="lang" --provider="PanicHD\PanicHDServiceProvider".
     • Add custom translations to resources/lang/en/panichd.php.

Debugging

1. Log Errors Enable debug mode in config/panichd.php:

   'debug' => env('APP_DEBUG', false),
   

   Check logs at storage/logs/laravel.log.

2. SQL Queries Use Laravel Debugbar or enable query logging:

   DB::enableQueryLog();
   // Run PanicHD actions...
   dd(DB::getQueryLog());
   

3. Common Issues

   • 404 on /PanicHD: Verify routes and middleware.
   • Blank Page: Check for PHP errors (enable display_errors in .env temporarily).
   • Attachments Not Saving: Ensure storage/app/public is writable and FILESYSTEM_DISK is correct.

Tips

1. Performance

   • Indexing: Add indexes to tickets table for large datasets:

     ALTER TABLE tickets ADD INDEX (status_id);
     ALTER TABLE tickets ADD INDEX (category_id);
     

   • Caching: Cache ticket lists if frequently accessed:

     $tickets = Cache::remember('panichd_tickets', 60, function () {
         return Ticket::all();
     });
     

2. Security

   • CSRF: PanicHD forms include CSRF tokens by default. For APIs, use VerifyCsrfToken middleware.
   • Rate Limiting: Protect ticket creation endpoints:

     Route::post('/api/tickets', function () {
         // ...
     })->middleware('throttle:10,1');
     

3. Testing

   • Unit Tests: Mock the PanicHD service:

     $panichd = Mockery::mock(\PanicHD\Facades\PanicHD::class);
     $panichd->shouldReceive('createTicket')->once();
     

   • Feature Tests: Use Laravel’s browser testing:

     $response = $this->get('/PanicHD/tickets/create');
     $response->assertStatus(200);
     

4. Extending Functionality

   • Custom Actions: Add buttons to tickets via Blade:

     <a href="{{ route('panichd.tickets.custom', $ticket) }}" class="btn btn-sm btn-info">
         Custom Action
     </a>
     

   • Webhooks: Trigger external actions on ticket events (e.g., Slack notifications):

     PanicHD::listen('ticket.updated', function ($ticket) {
         Http::post('https://hooks.slack.com/...', ['text' => "Ticket #{$ticket->id} updated"]);
     });
     

5. Localization

   • Multi-Lang Support: PanicHD supports translations