Tomato Freelancers Laravel Package

Getting Started

tomatophp/tomato-freelancers is a v0.0.1 package from the TomatoPHP ecosystem, intended to add freelancer management (profiles, skills, projects/bids, admin CRUD) to a Laravel app. Release notes for v0.0.1 are just a changelog link, so treat the source and README as the source of truth rather than release notes.

Minimal steps:

1. Install into an app that already runs the TomatoPHP admin base (typically tomatophp/tomato-admin or a Filament-based Tomato panel). This package almost certainly assumes that base rather than working standalone.
2. Require it: composer require tomatophp/tomato-freelancers
3. Publish assets/config/migrations if the package provides them: php artisan vendor:publish --provider="TomatoPHP\TomatoFreelancers\TomatoFreelancersServiceProvider" (check the actual provider name in composer.json/src/).
4. Run php artisan migrate. Inspect the migration files first — on a v0.0.1 package, table names and FKs are still in flux.
5. Clear caches: php artisan optimize:clear.
6. Look in this order: config/ for the package config, src/Models for the entities it ships, src/Tables/src/Resources (or src/Http/Controllers) for the admin surface, and database/migrations for the schema it assumes.

First use case: log into the admin panel, find the new freelancer menu entry, create a freelancer record with the required fields, and confirm the list/detail/edit screens work. That single round-trip tells you whether the package's assumptions (auth guard, panel registration, relationships) match your app.

Implementation Patterns

Treat it as an admin-panel module, not a domain library. The package's value is the pre-built CRUD and menu wiring. Keep your business logic in your own services/actions and let the package handle the admin surface.

Extend the shipped models, don't edit vendor files. Configure your own model via the package config (most TomatoPHP packages support swapping the model class) and subclass the provided one to add relationships, scopes, casts, and accessors. This is the safest extension point at v0.0.1.

Pattern: freelancer as an aggregate root. Typical wiring is Freelancer belongsTo User, and hasMany skills/portfolios/projects/bids. When you add fields, prefer a companion table or a JSON meta column over editing vendor migrations — you'll be able to upgrade without conflict.

Pattern: policy-gated admin, public read-only frontend. Use the package for the authenticated admin CRUD, then expose your own thin frontend controller/resource that reads the same models. Don't reuse the package's admin routes publicly.

Integration: events for cross-package reactions. If the package dispatches model events (it should, being Eloquent-based), hook observers rather than patching controllers — e.g. notify on freelancer approval, sync to a search index on profile update.

Testing workflow. Because v0.0.1 ships little to no test coverage, write your own feature test that boots the panel, hits the freelancer index route, and asserts a 200 for an authorized user. That test is your upgrade smoke test for every future version.

Pin and stage. In composer.json, use an exact version ("tomatophp/tomato-freelancers": "0.0.1") rather than ^0.0.1, and install on a branch/preview environment first.

Gotchas and Tips

• Pre-1.0 means no stability contract. At 0.0.1, config keys, table names, and class namespaces can change in any patch. Pin exactly and read the diff on every bump.
• Release notes are empty. There's no changelog content beyond a compare link. Diff v0.0.1 against the next tag yourself (git diff) before upgrading; don't rely on semantic versioning here.
• Migration collisions. Run php artisan migrate --pretend first. If a freelancers table already exists in your schema, the package migration will fail — rename via config or extend the existing table instead.
• Panel/guard mismatch. Admin resources typically assume a specific guard and panel. If menu items don't appear, check the panel provider registration and the package's config for an enabled/panel key rather than assuming the package is broken.
• Filament/Tomato version lockstep. TomatoPHP packages move fast against specific Filament versions. A minor Filament upgrade in your app can silently break resources; check composer.json constraints before upgrading either side.
• N+1 on relationship-heavy admin tables. Freelancer listings that eager-load skills/projects can degrade quickly; verify the table query uses with() and add indexes to any FK columns the package creates but doesn't index.
• Debugging blank admin pages. Check storage/logs/laravel.log for class-not-found errors from unregistered service providers, then confirm the provider is auto-discovered (php artisan about / package:discover).
• Extension points to prefer. Config-driven model/route swapping > service container bindings > subclassing controllers > editing vendor code. Stay as far left as possible while the package stabilizes.
• Have an exit plan. At this maturity, assume you may need to fork. Keep your customizations out of vendor/ and in your own app/ layer so a fork or replacement is a day's work, not a rewrite.