Getting Started

Minimal Steps to First Use

Install the Package:
```
composer require baks-dev/users-table
```
- Verify compatibility with your Laravel version (requires PHP 8.4+ and Laravel 10+).
Publish Configuration and Assets:
```
php artisan baks:assets:install
```
- This sets up necessary files (migrations, views, or config) in your project.
Run Migrations:
```
php artisan migrate
```
- The package includes migrations for attendance tables (e.g., user_attendance, shifts). Use --pretend first to review SQL:
```
php artisan migrate --pretend
```

Basic Usage:

Log a user's attendance via the UserAttendance model:

use BaksDev\UsersTable\Models\UserAttendance;

$attendance = UserAttendance::create([
    'user_id' => auth()->id(),
    'start_time' => now(),
    'end_time' => now()->addHours(8),
    'status' => 'active',
]);

Fetch a user's attendance records:

$records = UserAttendance::where('user_id', auth()->id())
    ->orderBy('start_time', 'desc')
    ->get();

Console Commands:
- Install assets (if not done already):
```
php artisan baks:assets:install
```
- Generate reports (if the package includes CLI tools):
```
php artisan baks:attendance:report --user=1 --month=2023-10
```
Testing:
- Run the package's test suite to verify core functionality:
```
php artisan test --group=users-table
```

Where to Look First

Package Source: Browse vendor/baks-dev/users-table/src for models, migrations, and services.
Config File: Check config/users-table.php (published via vendor:publish) for customizable settings (e.g., default time formats, validation rules).
Migrations: Inspect database/migrations/ for schema details (e.g., user_attendance table structure).
Models: Focus on UserAttendance, Shift, and Break models for CRUD operations.
Console Commands: List available commands with:
```
php artisan list baks
```

Implementation Patterns

Core Workflows

1. Attendance Logging

Pattern: Use the UserAttendance model to log punch-in/punch-out events.

// Punch-in
$attendance = UserAttendance::create([
    'user_id' => $user->id,
    'start_time' => now(),
    'status' => 'active',
]);

// Punch-out (auto-calculates duration)
$attendance->update([
    'end_time' => now(),
    'status' => 'completed',
]);

Validation: Leverage Laravel's built-in validation or extend the model with custom rules:

use Illuminate\Validation\Rule;

$validated = request()->validate([
    'start_time' => 'required|date',
    'end_time' => [
        'required_with:start_time',
        'after:start_time',
        Rule::unique('user_attendance')->ignore($attendance->id),
    ],
]);

2. Shift Management

Pattern: Define shifts via the Shift model and associate them with attendance:

$shift = Shift::create([
    'name' => 'Morning Shift',
    'start_time' => '09:00',
    'end_time' => '17:00',
]);

$attendance->shift()->associate($shift);
$attendance->save();

Bulk Assignment: Use Laravel collections to assign shifts to multiple users:

$users = User::whereIn('id', [1, 2, 3])->get();
$shift = Shift::find(1);

$users->each(function ($user) use ($shift) {
    $user->attendances()->create([
        'shift_id' => $shift->id,
        'start_time' => now(),
    ]);
});

3. Break Tracking

Pattern: Log breaks using the Break model, linked to attendance records:

$break = Break::create([
    'attendance_id' => $attendance->id,
    'start_time' => now(),
    'end_time' => now()->addMinutes(30),
    'duration' => 30, // in minutes
]);

Auto-Calculation: Extend the UserAttendance model to calculate net working time:

public function getNetDurationAttribute()
{
    $totalDuration = $this->start_time->diffInMinutes($this->end_time);
    $breaksDuration = $this->breaks->sum('duration');
    return $totalDuration - $breaksDuration;
}

4. Reporting

Pattern: Generate reports using Eloquent queries or the package's CLI tools:

// Monthly report for a user
$report = UserAttendance::where('user_id', $user->id)
    ->whereMonth('start_time', now()->month)
    ->with(['shift', 'breaks'])
    ->get()
    ->map(function ($record) {
        return [
            'date' => $record->start_time->format('Y-m-d'),
            'duration' => $record->net_duration,
            'shift' => $record->shift->name,
        ];
    });

CSV Export: Use Laravel Excel or similar packages to export reports:

use Maatwebsite\Excel\Facades\Excel;

return Excel::download(new UserAttendanceExport($user), 'attendance_'.$user->id.'.csv');

5. API Integration

Pattern: Expose attendance data via Laravel API resources:

// routes/api.php
Route::apiResource('attendance', \BaksDev\UsersTable\Http\Controllers\UserAttendanceController::class)
    ->middleware('auth:sanctum');

Webhooks: Trigger events for third-party integrations (e.g., payroll systems):

// Event listener for attendance logging
UserAttendance::created(function ($attendance) {
    event(new AttendanceLogged($attendance));
});

// Listen for the event
AttendanceLogged::listen(function ($event) {
    // Send webhook to payroll system
    Http::post('https://payroll.example.com/webhook', [
        'user_id' => $event->attendance->user_id,
        'hours' => $event->attendance->net_duration / 60,
    ]);
});

Integration Tips

Laravel Ecosystem

Authentication: Ensure the package works with your auth system (e.g., Sanctum, Passport). Extend policies if needed:

// app/Policies/UserAttendancePolicy.php
public function viewAny(User $user)
{
    return $user->isAdmin(); // Customize access logic
}

Notifications: Use Laravel Notifications to alert users/managers:

$attendance->user->notify(new AttendanceLoggedNotification($attendance));

Scheduling: Use Laravel Tasks to generate daily/weekly reports:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('baks:attendance:report:weekly')->dailyAt('18:00');
}

Frontend Integration

Livewire/Inertia: Create a dashboard to view/edit attendance:

// app/Http/Livewire/UserAttendanceDashboard.php
public function render()
{
    return view('livewire.user-attendance-dashboard', [
        'attendances' => UserAttendance::with(['user', 'shift'])->latest()->get(),
    ]);
}

Nova Resources: Extend Laravel Nova for admin management:

// app/Nova/UserAttendance.php
public static $model = \BaksDev\UsersTable\Models\UserAttendance::class;
public static $title = 'attendance';

Testing

Unit Tests: Test models and logic:

public function test_attendance_creation()
{
    $user = User::factory()->create();
    $attendance = UserAttendance::create([
        'user_id' => $user->id,
        'start_time' => now(),
    ]);

    $this->assertDatabaseHas('user_attendance', [
        'user_id' => $user->id,
        'status' => 'active',
    ]);
}

Feature Tests: Test API endpoints or UI interactions:

public function test_attendance_api()
{
    $response = $this->actingAs(User::factory()->create())
        ->post('/api/attendance', [
            'start_time' => now(),
        ]);

    $

Users Table Laravel Package