Getting Started

Minimal Setup

Install the Package

composer require baks-dev/users-profile-user

Publish Assets and Migrations

php artisan baks:assets:install
php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate

First Use Case: Basic Profile CRUD
- Model Access: Use the Profile model (likely BaksDev\UsersProfileUser\Models\Profile) to fetch/update profiles:
```
use BaksDev\UsersProfileUser\Models\Profile;

$profile = Profile::where('user_id', auth()->id())->first();
$profile->bio = 'Updated bio';
$profile->save();
```
- Validation: Leverage built-in validation rules (check Rules class in the package for field-specific rules like avatar_size or bio_length).
Frontend Integration
- Include Blade templates (published via baks:assets:install) in your views:
```
@include('users-profile-user::profile.form')
```
- Customize templates by extending the package’s views in resources/views/vendor/users-profile-user/.

Implementation Patterns

Core Workflows

Profile Creation/Update

Form Handling: Use the package’s form request classes (e.g., StoreProfileRequest, UpdateProfileRequest) to handle validation:

use BaksDev\UsersProfileUser\Http\Requests\UpdateProfileRequest;

public function update(UpdateProfileRequest $request) {
    $profile = Profile::find($request->profile_id);
    $profile->update($request->validated());
}

Events: Listen for profile updates via Laravel events (check the package’s Events class):

Profile::updated(function ($profile) {
    // Trigger notifications, analytics, etc.
});

File Uploads (Avatars)
- Configuration: Set storage paths in config/users-profile-user.php:
```
'avatar' => [
    'disk' => 'public',
    'path' => 'avatars',
],
```
- Usage: Attach files via the avatar field in forms. The package handles uploads and resizing (if configured).

API Endpoints

RESTful Routes: The package likely includes routes in routes/api.php or routes/web.php. Extend them if needed:
```
Route::put('/profile', [ProfileController::class, 'update'])->middleware('auth:sanctum');
```

API Resources: Use Laravel’s ApiResource for JSON responses:

namespace App\Http\Resources;
use BaksDev\UsersProfileUser\Models\Profile;
use Illuminate\Http\Resources\Json\JsonResource;

class ProfileResource extends JsonResource {
    public function toArray($request) {
        return [
            'id' => $this->id,
            'bio' => $this->bio,
            'avatar' => $this->avatar_url,
        ];
    }
}

Custom Fields

Extending Schema: Add custom fields via a migration:

Schema::table('profiles', function (Blueprint $table) {
    $table->string('custom_field')->nullable();
});

Form Integration: Extend the package’s form templates or use partials:
```
@include('users-profile-user::profile.partials.custom-field')
```

Authorization

Policies: Attach Laravel policies to the Profile model:

use Illuminate\Auth\Access\HandlesAuthorization;

class ProfilePolicy {
    use HandlesAuthorization;

    public function update(User $user, Profile $profile) {
        return $user->id === $profile->user_id;
    }
}

Middleware: Protect routes with can middleware:

Route::put('/profile', [ProfileController::class, 'update'])
     ->middleware(['auth:sanctum', 'can:update,profile']);

Gotchas and Tips

Pitfalls

Database Conflicts
- Issue: The package may assume a profiles table or specific column names (e.g., avatar_path). Conflicts can arise if your app uses a different schema (e.g., user_profiles).
- Fix: Review migrations before running doctrine:migrations:migrate. Use Laravel’s schema builder for hybrid migrations if needed:
```
Schema::table('user_profiles', function (Blueprint $table) {
    $table->string('avatar_path')->nullable()->default(null);
});
```
Asset Pipeline Conflicts
- Issue: The baks:assets:install command may overwrite existing frontend assets or conflict with Vite/Laravel Mix.
- Fix: Customize asset paths in config/users-profile-user.php or manually publish assets:
```
php artisan vendor:publish --tag=users-profile-user-assets
```
Authentication Integration
- Issue: The package may not integrate seamlessly with third-party auth (e.g., Sanctum, Passport). Profile routes might not respect your auth middleware.
- Fix: Override the package’s routes or middleware in your AppServiceProvider:
```
public function boot() {
    Route::middleware('auth:sanctum')->group(function () {
        require __DIR__.'/../routes/api.php';
    });
}
```

Validation Overrides

Issue: Built-in validation rules (e.g., avatar_size) may not align with your app’s requirements.

Fix: Extend the package’s form requests:

namespace App\Http\Requests;
use BaksDev\UsersProfileUser\Http\Requests\UpdateProfileRequest;

class CustomUpdateProfileRequest extends UpdateProfileRequest {
    protected function rules() {
        return array_merge(parent::rules(), [
            'avatar' => 'nullable|image|mimes:jpeg,png|max:2048',
        ]);
    }
}

Localization Gaps
- Issue: Validation messages or UI text may not be localized (e.g., Russian-only defaults).
- Fix: Publish and override language files:
```
php artisan vendor:publish --tag=users-profile-user-lang
```
  Then customize resources/lang/en/users-profile-user.php.
Performance with Eager Loading
- Issue: N+1 queries if profiles are accessed via relationships (e.g., User::with('profile')->get()).
- Fix: Eager-load profiles explicitly:
```
User::with(['profile' => function ($query) {
    $query->select('id', 'user_id', 'bio', 'avatar_path');
}])->get();
```

Debugging Tips

Log Package Events

Enable Laravel’s debug mode and log events to understand the package’s workflow:

Profile::updated(function ($profile) {
    \Log::info('Profile updated', ['profile_id' => $profile->id]);
});

Check Console Output
- Run migrations with verbose output to debug schema changes:
```
php artisan doctrine:migrations:migrate --verbose
```
Inspect Published Files
- After baks:assets:install, check public/vendor/users-profile-user/ for uploaded assets and templates.
Test Edge Cases
- Test profile updates with:
  - Large file uploads (e.g., 10MB avatars).
  - Concurrent updates (simulate race conditions).
  - Malformed data (e.g., invalid image formats).

Extension Points

Custom Profile Fields

Approach: Extend the Profile model and migration:

// app/Models/Profile.php
namespace App\Models;
use BaksDev\UsersProfileUser\Models\Profile as BaseProfile;

class Profile extends BaseProfile {
    protected $casts = [
        'custom_field' => 'array',
    ];
}

Event Listeners

Approach: Subscribe to package events in EventServiceProvider:

protected $listen = [
    \BaksDev\UsersProfileUser\Events\ProfileUpdated::class => [
        \App\Listeners\LogProfileUpdate::class,
    ],
];

API Resource Customization

Approach: Override the package’s API resource:

namespace App\Http\Resources;
use BaksDev\UsersProfileUser\Http\Resources\ProfileResource as BaseProfileResource;

class ProfileResource extends BaseProfileResource {
    public function toArray($request) {
        return array_merge(parent::toArray($request), [
            'custom_field' => $this->custom_field,
        ]);
    }
}

Middleware for Profile Access

Approach: Create a custom middleware to restrict profile access:

namespace App\Http\Middleware;
use Closure;
use BaksDev\UsersProfileUser\Models\Profile;

class ProfileAccess

Users Profile User Laravel Package