Tomato Tasks Laravel Package

Getting Started

• Install with Composer, pinning the patched release: composer require tomatophp/tomato-tasks:^1.0.2.
• Publish the package assets you need. Typical commands are:

  php artisan vendor:publish --tag=tomato-tasks-config
  php artisan vendor:publish --tag=tomato-tasks-migrations
  php artisan migrate
  

  Check the package README for the exact publish tags and whether config publishing is optional.
• Look first at:
  • config/tomato-tasks.php for model, table, middleware, and UI options.
  • The package migrations for task fields and foreign keys.
  • src/Models/Task.php for fillable fields, relationships, casts, and scopes.
  • The Filament resource/plugin class if you are using TomatoPHP’s admin panel.
• Register the package’s Filament plugin in your panel provider if the package does not auto-register it. The exact plugin class is the main thing to confirm in the README.
• First use case: open the Tasks resource in your admin panel, create a task, assign it to a user, set status/priority/due date, and verify it appears in the task list. Then create one programmatically to confirm your model integration:

  use TomatoPHP\TomatoTasks\Models\Task;
  
  $task = Task::create([
      'name' => 'Follow up with lead',
      'description' => 'Call before end of day',
      'user_id' => auth()->id(),
      // Set status/priority only if those fields exist in your published migration.
  ]);
  

Implementation Patterns

• Admin-first CRUD. Use the supplied Filament resource for day-to-day task management: list/filter by status, assignee, due date, and priority; use bulk actions for reassignment or closing. This is the lowest-friction path and keeps you aligned with package updates.
• Programmatic task creation. Create tasks from domain events, e.g. after an order is placed or a support ticket is opened:

  Task::create([
      'name' => "Review order #{$order->id}",
      'user_id' => $order->assigned_user_id,
      'due_at' => now()->addDay(),
  ]);
  

  Confirm field names against the published migration before relying on them.
• Integrate via the model, not the admin UI. For API endpoints, dashboards, or notifications, query the Task model directly and wrap it in your own controller/resource. Avoid coupling business logic to Filament resource classes.
• Config-driven model swapping. If the config exposes a models.task key, point it at your own subclass to add scopes, relationships, or audit behavior without forking:

  // config/tomato-tasks.php
  'models' => [
      'task' => App\Models\Task::class,
  ],
  

• Extend the Filament resource. Subclass the package resource or use Filament’s form/table extension APIs to add tenant, project, or custom-field columns. Keep custom fields in your own migration so package upgrades stay clean.
• Authorization. Add a TaskPolicy and register it. Filament resources are often visible to any panel user by default; enforce ownership/team access explicitly.
• Scheduled workflows. Use Laravel’s scheduler to create recurring tasks or flag overdue items:

  Schedule::call(function () {
      Task::where('due_at', '<', now())
          ->whereNull('completed_at')
          ->update(['is_overdue' => true]);
  })->daily();
  

  Adjust column names to match your schema.
• Testing. Use RefreshDatabase and create tasks through the model or factory. Test empty assignees/relations because v1.0.2 specifically addresses array-key and property-access failures.

Gotchas and Tips

• v1.0.2 is a patch release. It fixes “Undefined Array Key 0” and property-access errors. There are no announced breaking changes, so upgrading from v1.0.1 should be safe. Run composer update tomatophp/tomato-tasks and then php artisan optimize:clear.
• Remove old workarounds carefully. If you previously guarded against missing index 0 in config arrays or null relation access, keep tests around those paths. The fix likely covers empty arrays/missing relations, but custom config overrides may still produce shapes the package does not expect.
• Empty defaults can still bite. If you publish config and set status/priority/default-assignee arrays to [], verify the UI and programmatic creation still work. Keep at least one default value where the package expects one, or guard your own code with array_key_first() / reset().
• Null relations. Property-access errors often come from accessing $task->user->name when user_id is null. Use $task->user?->name and make assignee columns nullable where appropriate.
• Migration publishing order. Publish migrations before running php artisan migrate. If the table already exists, do not republish over it; create a new migration for schema changes.
• Filament version alignment. Check the package’s composer.json constraints against your Filament major version. A mismatch can surface as missing plugin classes or resource errors rather than an obvious dependency failure.
• Permissions. Configure policies and panel access before exposing the Tasks resource to non-admin users. Task visibility is often the first security issue in task-management integrations.
• Timezone handling. Store due dates in UTC and render them in the user’s timezone. Filament date-time fields can otherwise appear shifted.
• Debugging. Reproduce failures with an empty task list, a task with no assignee, and a task with missing optional fields. Check storage/logs/laravel.log and clear cached config/routes after changing published config.
• Extension points to prefer. Use the config model mapping, model events/observers, a custom policy, and Filament resource extension hooks. Avoid editing vendor files so future patch releases remain drop-in.