Laraveleasyattendance Laravel Package

Getting Started

Install and publish

composer require easybdit/laraveleasyattendance
php artisan vendor:publish --tag=laraveleasyattendance-config
php artisan vendor:publish --tag=laraveleasyattendance-migrations
php artisan migrate

Where to look first

1. config/attendance.php — the attendance.subject_model key is the single most important setting. It points at your app's model (usually App\Models\Employee or App\Models\User) that attendance records attach to.
2. src/Traits/HasAttendance.php — the contract your subject model must satisfy.
3. src/Traits/HasPackageTable.php — table-name resolution and query plumbing used by the package models.
4. src/Http/Controllers/AttendanceController.php — read the class docblock; it explains the runtime-model indirection that also explains the package's remaining static-analysis limitations.
5. src/Models/ — Leave, AttendanceSummary, SalarySlip, Designation, EmployeeShift. As of v2.3.1 every one of these ships a complete @property / @property-read docblock, so your IDE resolves columns, cast types, and relations the moment you use them.

First use case

Add the trait to your subject model, then record a day of attendance:

// app/Models/Employee.php
use Easybdit\LaravelEasyAttendance\Traits\HasAttendance;

class Employee extends Model
{
    use HasAttendance;
}

// config/attendance.php
'subject_model' => App\Models\Employee::class,

$employee->attendances()->create([
    'date'       => now()->toDateString(),
    'shift_id'   => $shift->id,
    'check_in'   => '09:02:00',
    'check_out'  => '18:11:00',
]);

That's the minimum viable loop: install → point subject_model at your model → use HasAttendance → write a row. Everything else (summaries, salary slips, leave balances) is derived from that.

Implementation Patterns

Let the typed relations drive your queries. v2.3.1 added explicit BelongsTo return types to AttendanceSummary::employee(), SalarySlip::employee(), Designation::department(), and EmployeeShift::shift(). This isn't cosmetic — Larastan only recognizes a method as a relation (and therefore validates ->with('employee') relation names) when it has a typed return. Your own relations on the subject model should follow the same rule if you want the same safety.

AttendanceSummary::with('employee.department')
    ->whereBetween('month', [$start, $end])
    ->get();

Lean on the docblocks in consuming code. Because every package model now carries full @property / @property-read annotations, $slip->employee, $summary->employee, $leave->daysCount() etc. autocomplete in PhpStorm and Intelephense without you generating stubs or running a separate ide-helper pass over the vendor directory. Combine with Laravel Idea / barryvdh ide-helper for your own models and the whole graph is typed.

Model the org chart once, reuse it. Designation::department() ties a job title to a department; EmployeeShift::shift() ties a shift assignment to a shift definition. Seed these once and treat them as reference data — attendance rows should reference shift_id, not duplicate times.

Summaries as a materialized view. Treat AttendanceSummary as a derived, rebuildable table rather than a source of truth. Compute from raw attendance for a month, upsert into summaries, and let salary slips read from summaries only. That keeps a bad summary fixable with a re-run instead of a data repair.

Salary slips read from summaries, not from attendance. SalarySlip::employee() plus the summary for the period is the natural join. Keep the slip generation in a queued job or command so a large payroll run doesn't time out a request.

Leave arithmetic with date-only casts. Leave::daysCount() is int-returning and, since v2.3.1, explicitly casts Carbon's diffInDays() result. Rely on the method rather than recomputing in your views — the cast-to-int contract is the stable API, the underlying float is not.

Config-driven subject model = test seam. In tests, point attendance.subject_model at a fixture model in setUp() (or via config()->set() before the package resolves it). This is the cleanest way to exercise HasAttendance against a known schema.

Gotchas and Tips

The subject_model indirection defeats static analysis — by design. The 16 findings still in phpstan-baseline.neon are all the same pattern: HasAttendance / HasPackageTable methods invoked through a runtime-configured model that could be any consuming app's class. Static analysers cannot know which class that is. This is genuine unknowability, not a bug — the docblock on AttendanceController documents it. Don't try to "fix" it in a PR; if it bothers you, narrow the type with a local @var annotation at the call site.

Don't call HasAttendance methods on a Model-typed variable. Related to the above: $model->attendances() on a bare Model will fail both PHPStan and, at runtime, if the model doesn't actually use the trait. Always type the variable as your concrete subject model.

Relation names in with() are validated only when typed. If you add a relation method to your subject model and ->with('thatRelation') silently returns nothing useful in analysis, check for a missing BelongsTo / HasMany return type. v2.3.1 fixed exactly this for four package relations — mirror the pattern, don't skip the return type.

diffInDays() returns float upstream. It carries sub-day precision that cannot occur between two date-only casts. If you compute your own leave or tenure arithmetic, cast to int explicitly. v2.3.1 hardened Leave::daysCount() for this; the same trap exists in your app code.

Config caching hides subject_model changes. After editing config/attendance.php, run php artisan config:clear in dev and php artisan config:cache in deploy. A stale cached config pointing at the wrong model produces confusing "method does not exist" errors rather than a clean failure.

Migration ordering matters. Publish and run the package migrations after your employees/users table exists — attendance foreign keys reference the subject table indirectly through configuration, but shifts, designations, and departments are real FKs. On a fresh install, order your own migrations first.

Date vs datetime casting. Attendance columns are date-only in the models' casts. Passing a full Carbon with a time component to a date cast silently truncates — fine for daily attendance, surprising if you were expecting timestamp fidelity. Store times in the dedicated check_in / check_out columns.

Eager-load the employee relation on list screens. Summaries and slips are the two places people render tables of hundreds of rows with an employee name column. Without ->with('employee') you get an N+1 that's invisible at seed volume and painful in production.

Extension point: subclass, don't fork. If you need extra columns on summaries or slips, add them via your own migration on the package table and extend the package model, rather than editing vendor files. The typed docblocks in v2.3.1 make it obvious which properties the package itself relies on.

Debugging trick. When behaviour differs between environments, dump config('attendance.subject_model') and app(config('attendance.subject_model'))::class. Most "package is broken" reports turn out to be a cached config or a subject model that forgot the trait.