Filament Employees Laravel Package

Getting Started

This release targets Filament v5 / Laravel 12–13 / Livewire 4 / PHP 8.2+. If you are still on Filament v3, stay on the v3 branch; do not upgrade this package to ^5.0 until your panel is on v5.

Minimal setup:

1. Require the package and its v5 dependencies:

   composer require tomatophp/filament-employees:^5.0 \
     tomatophp/filament-accounts:^5.0 \
     tomatophp/filament-types:^5.0 \
     tomatophp/filament-meta:^5.0
   

2. Run the package install command. It no longer runs yarn in the host application, so any frontend asset build is your responsibility.
3. Publish and run migrations, including the meta migrations required by HasMeta.
4. Configure the user/account models in the package config. The release makes these config-driven, so point them at your application’s account model rather than assuming the package default.
5. Register the plugin in your Filament panel provider, then open the employee resource. The first useful workflow is the employee directory: create an employee, attach the account/user, and fill the profile meta fields.

Look first at the README’s account model setup section, the package config file, and the generated Filament resources. Those three places explain most of the integration surface.

Implementation Patterns

Use meta for employee profile data. IsEmployee now includes HasMeta, so profile fields are stored through tomatophp/filament-meta rather than requiring a new column for every attribute. For day-to-day work, define profile fields as meta and read/write them through the meta API. This keeps the employee table stable while allowing HR-specific fields to evolve.

Keep account/user resolution config-driven. Resolve the user and account models from config instead of hard-coding your User or Account class. This is important for apps with custom authentication models, multiple guards, or separate employee/account tables. In tests, bind the configured models explicitly so the package resolves the same classes as production.

Model attendance around optional shifts and departments. The release explicitly supports attendance without a shift or department and optional shift days off. Build attendance forms and reports with nullable relationships. A common pattern is:

• Employee + date as the attendance identity.
• Optional shift and department for scheduling/reporting.
• Null shift/department for manual or imported attendance.
• Notes with a consistent author resolution path.

Treat payroll as account-backed. Payroll uses the configured account model and salary data. When building payroll screens or exports, resolve the account through the same config-driven path as the rest of the package. Avoid joining directly to a hard-coded accounts table.

Use the provided factories for shift and apply testing. The new factories for shifts and applies make Pest feature tests much cheaper. A typical pattern is to create an employee, optionally attach a shift/department, create attendance, then assert payroll or attendance behavior. Use RefreshDatabase and the package factories rather than hand-building models.

Extend through Filament resources and config, not forks. The release fixes duplicate header action names and account column labels, which suggests these resources are meant to be extended. Override resource classes, table columns, and form schemas in your app. For applies, the National ID option can be enabled per form/configuration rather than assumed globally.

For job applies, keep National ID optional. The release adds a National ID option for applies. If your jurisdiction or privacy policy does not require it, leave it disabled and validate conditionally when enabled.

Gotchas and Tips

• v5 is a hard upgrade boundary. Filament v5, Livewire 4, Laravel 12/13, and PHP 8.2+ are required. The dependent packages must also be ^5.0. Mixing a v5 employee package with v3 accounts/types/meta packages will fail.
• IsEmployee now pulls in HasMeta. Existing employee models or migrations may need the meta table and trait setup. Check for duplicate trait inclusion if your app already uses HasMeta on the employee model.
• Config changes need a cache clear. Because user/account models are config-driven, run php artisan config:clear after changing them. In production, ensure config:cache runs after the config is correct.
• The install command no longer runs yarn. If you rely on package-provided frontend assets, build them in your host app or ensure published assets are current. Do not expect the installer to compile anything.
• Attendance nullability is intentional. Do not assume every attendance row has a shift or department. Add null checks in custom reports, exports, and payroll calculations. The same applies to optional shift days off.
• Notes author resolution changed. If you have custom note creation, verify the author is resolved from the expected guard/user model. This was a fix area, so custom code that manually set authors may now conflict.
• Header action names changed/fixed. If you extended or replaced header actions, re-check action names. Duplicate names were fixed, so custom actions may need renaming to avoid collisions.
• DatePicker class name changed. Update any custom imports or subclassing that referenced the old class name.
• Migration rollbacks were fixed. Test migrate:rollback in a disposable database, especially with meta tables and payroll/attendance tables. Rollback order can matter when meta depends on employees.
• Static analysis is only PHPStan level 0. The package’s CI passing at level 0 does not guarantee strong type safety. Add your own tests around payroll and attendance edge cases.
• Use the Pest suite as documentation. The new full Pest suite, factories, and CI are the best reference for expected behavior. Read the shift/apply tests before building custom flows.
• Debugging order: check config model resolution first, then meta values, then Filament resource/action registration. Most “missing employee data” issues in this package will be a misconfigured account model or missing meta row rather than a database failure.