Tomato Hr Laravel Package

Getting Started

• Treat v1.0.0 as the initial baseline. The release notes are intentionally sparse and only link the changelog, so verify the actual surface area from the README, composer.json, service provider, migrations, and Filament resources after install.
• Minimal install path:
  1. composer require tomatophp/tomato-hr
  2. Publish the package config/migrations/assets using the provider or tags documented by the package.
  3. Run php artisan migrate.
  4. Register the package service provider/Filament plugin in your panel as documented.
  5. Seed or create base HR data: departments, roles/permissions, then employees.
• Look first at:
  • README.md and CHANGELOG.md
  • config/tomato-hr.php
  • database/migrations
  • the package service provider
  • Filament resources/pages under src/ or src/Filament
  • any policies, events, or observers shipped with the package
• First practical use case: stand up an internal HR back office. Create a department, create an employee record, link that employee to a Laravel user if supported, then exercise one HR workflow such as leave/attendance before expanding into payroll or reporting.

Implementation Patterns

• Use it as a Filament-first HR module rather than a standalone domain layer. Keep UI concerns in Filament resources and put reusable business rules in your own services/actions so payroll, leave, and attendance logic can be tested without the admin panel.
• Link employees to Laravel users deliberately. If the package exposes a user_id or similar relation, decide whether every employee needs a login, whether managers need scoped access, and whether historical employees should remain unlinked.
• Model workflows around explicit actions:
  • onboarding an employee
  • transferring departments
  • approving/rejecting leave
  • importing attendance
  • generating payroll or reports
• Wrap multi-table operations in database transactions. Employee onboarding, department transfers, leave approvals, and payroll generation should not leave partial records if a downstream step fails.
• Use policies and Filament authorization rather than hiding buttons only in the UI. HR data is sensitive; ensure managers can only see their teams and employees can only see permitted self-service records.
• Prefer relation managers and scoped queries for employee sub-records. For example, keep attendance, leave, contracts, and documents reachable from the employee record while enforcing tenant/department scoping.
• For imports/exports and payroll-style batch work, use queued jobs and store status/results. Avoid long-running work directly in Filament actions.
• Integrate through events/observers where available, but dispatch notifications after commit. Good candidates are employee created, leave approved, attendance imported, and payroll finalized.
• Test with RefreshDatabase and seed minimal HR data. Build factories for departments/employees if the package does not provide them, and add feature tests around permissions and approval flows.

Gotchas and Tips

• Pin the version. v1.0.0 is a first release; minor updates may still change APIs, resource names, config keys, or migrations. Read the changelog before upgrading and avoid unbounded constraints in production.
• Inspect migrations before running in a shared database. Check table names, foreign keys, nullable columns, and whether the package assumes an existing users/teams table.
• Verify Laravel, PHP, Filament, and Livewire compatibility from composer.json. A mismatch here is the most common install-time failure in Filament-based packages.
• Permissions are often not automatically seeded. After install, check whether roles/permissions are created and assign them explicitly to admin, HR, manager, and employee roles.
• Time zones and date boundaries matter for attendance and leave. Confirm whether dates are stored as dates, datetimes, or UTC timestamps, and test leave spanning month/year boundaries.
• Be careful deleting employees. Historical attendance, leave, payroll, and documents should usually restrict deletion or use soft deletes. Test what the package does by default.
• Use decimal/integer casts for money. Do not rely on floats for payroll or salary fields; confirm column types and model casts before building reports.
• If the package publishes config, run php artisan config:clear during development and remember config:cache in production. Config changes can appear ignored if the cache is stale.
• If file uploads are supported, run php artisan storage:link and check disk configuration. Employee documents and avatars are common sources of broken links.
• Prefer extension over vendor edits:
  • override config values
  • bind custom implementations where the package supports it
  • extend Filament resources/pages
  • use observers/events for side effects
• Debug in this order: php artisan about, provider registration, published config, migration status, Filament panel plugin registration, policies, then application logs. Most “resource missing” issues are provider/plugin registration or authorization, not missing code.