Getting Started

Minimal Steps to First Use

Install the Package
```
composer require baks-dev/users-user
```
Ensure your composer.json has "php": "^8.4" and "laravel/framework": "^10.0".
Publish Assets and Configure Run the package’s CLI command to install configurations and assets:
```
php artisan baks:assets:install
```
This typically generates:
- Configuration files (e.g., config/users-user.php).
- Migration files (e.g., database/migrations/YYYY_MM_DD_create_users_table.php).
- Optional: Views, language files, or other resources in resources/ or vendor/.
Run Migrations Generate and apply the migration to your database:
```
php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate
```
If using Eloquent, ensure no conflicts with existing users table migrations.

Verify the User Model The package likely registers a User model in app/Models/User.php (or App\Models\User). Check its traits, fillable fields, and relationships:

// Example: Check if the model uses traits like `HasRoles`, `SoftDeletes`, etc.
use BaksDev\UsersUser\Models\Traits\HasRoles;
use Illuminate\Database\Eloquent\SoftDeletes;

class User extends Authenticatable
{
    use HasRoles, SoftDeletes;
    // ...
}

First Usage in Code Use the User model in a controller or service:

use BaksDev\UsersUser\Models\User;

// Create a user
$user = User::create([
    'email' => 'user@example.com',
    'password' => bcrypt('password123'),
    'role' => 'admin', // Assuming HasRoles trait
]);

// Query users
$users = User::where('role', 'admin')->get();

Test the Implementation Run the package’s test group to verify core functionality:
```
php artisan test --group=users-user
```

Implementation Patterns

Common Workflows

1. Extending the User Model

Override or extend the User model to add custom fields or logic:

// app/Models/User.php
namespace App\Models;

use BaksDev\UsersUser\Models\User as BaseUser;
use Illuminate\Database\Eloquent\Relations\HasMany;

class User extends BaseUser
{
    protected $fillable = [
        'email',
        'password',
        'role',
        'custom_field', // Add custom fields
    ];

    public function customRelationship(): HasMany
    {
        return $this->hasMany(CustomModel::class);
    }
}

2. Customizing Migrations

If the package’s migrations conflict with existing ones, create a custom migration:

php artisan make:migration add_custom_fields_to_users_table --table=users

Then extend the table schema in the new migration.

3. Integrating with Authentication

Configure Laravel’s auth to use the package’s User model:

// config/auth.php
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => BaksDev\UsersUser\Models\User::class,
    ],
],

For Sanctum/Passport, ensure the User model implements the required interfaces (e.g., HasApiTokens).

4. Role-Based Access Control (RBAC)

If the HasRoles trait is included, use it for authorization:

use Spatie\Permission\Traits\HasRoles; // If using Spatie, or the package's trait

// Assign a role
$user->assignRole('editor');

// Check role
if ($user->hasRole('admin')) {
    // Grant access
}

5. Soft Deletes

Enable soft deletes if the SoftDeletes trait is used:

// In a controller or service
$user = User::find(1);
$user->delete(); // Sets `deleted_at` instead of hard delete

// Query soft-deleted users
$deletedUsers = User::onlyTrashed()->get();

6. Events and Observers

Listen to user events (e.g., created, deleted) for side effects:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \BaksDev\UsersUser\Events\UserCreated::class => [
        \App\Listeners\LogUserCreation::class,
    ],
];

7. API Resources

Create a custom API resource for the User model:

php artisan make:resource UserResource

// app/Http/Resources/UserResource.php
public function toArray($request)
{
    return [
        'id' => $this->id,
        'email' => $this->email,
        'role' => $this->role,
        'custom_field' => $this->custom_field,
    ];
}

8. Testing

Write tests for your custom logic using the package’s test group as a reference:

// tests/Feature/UserTest.php
public function test_user_creation()
{
    $user = User::create([
        'email' => 'test@example.com',
        'password' => bcrypt('password'),
    ]);

    $this->assertDatabaseHas('users', [
        'email' => 'test@example.com',
    ]);
}

Integration Tips

Avoid Doctrine-Eloquent Conflicts If your project uses Eloquent, ensure the package’s migrations don’t override existing ones. Use a custom migration to extend the users table instead of replacing it.

Leverage Laravel’s Service Container Bind the package’s services to the container for easier mocking in tests:

// config/app.php
'bindings' => [
    BaksDev\UsersUser\Repositories\UserRepository::class => function ($app) {
        return new \App\Repositories\UserRepository();
    },
];

Use Traits for Shared Logic Extract reusable logic into traits to avoid duplication:

// app/Traits/HasCustomUserFields.php
trait HasCustomUserFields
{
    protected $fillable = ['custom_field'];

    public function getCustomAttribute()
    {
        return $this->custom_field;
    }
}

Customize Validation Rules Override the package’s validation logic in a Form Request:

// app/Http/Requests/StoreUserRequest.php
public function rules()
{
    return [
        'email' => 'required|email|unique:users',
        'password' => 'required|min:8',
        'custom_field' => 'nullable|string|max:255',
    ];
}

Localization If the package includes language files, publish and customize them:
```
php artisan vendor:publish --tag=users-user-lang
```
Document Customizations Maintain a CUSTOMIZATIONS.md file in your project to track changes to the package’s default behavior.

Gotchas and Tips

Pitfalls

Migration Conflicts
- Issue: The package’s migrations may assume a clean users table, causing conflicts if your project already has one.
- Fix: Run doctrine:migrations:diff first to inspect changes, then merge manually or create a custom migration.
Doctrine vs. Eloquent
- Issue: The package uses Doctrine, which may not play nicely with Eloquent’s create_users_table migration.
- Fix: Disable Eloquent’s migration and rely solely on Doctrine’s migrations.
Undocumented Configuration
- Issue: The package may rely on undocumented config keys or environment variables.
- Fix: Check config/users-user.php and inspect the package’s ServiceProvider for bindings.
Russian Documentation
- Issue: The README and docs are in Russian, which may obscure critical setup steps.
- Fix: Use a translation tool or ask the community for clarifications. Document your setup in English for your team.
No Built-in Auth UI
- Issue: The package provides only the User model, not views or controllers for login/signup.
- Fix: Pair it with Laravel Jetstream, Breeze, or Fortify for frontend auth.
CLI Command Conflicts
- Issue: The baks:assets:install command may conflict with Laravel’s Artisan commands.
- Fix: Ensure the package’s commands are namespaced properly or override them in your AppServiceProvider.
Testing Gaps
- Issue: The package’s tests may not cover Laravel-specific workflows (e.g., API responses, middleware).

Users User Laravel Package