Getting Started

Minimal Steps

Install or upgrade:
```
composer require tastyigniter/ti-ext-user
php artisan igniter:up
```
For v4.2.1, update with:
```
composer update tastyigniter/ti-ext-user
php artisan optimize:clear
```
v4.2.1 contains bug fixes and searchable-field additions; no new migration is called out in the release notes.
Publish config:
```
php artisan vendor:publish --provider="TastyIgniter\TiExtUser\Providers\TiExtUserServiceProvider"
```
Review config/ti-ext-user.php for registration defaults, email settings, password reset expiry, and permissions.
First use case — registration and login: Use the package Blade views or route users through the default auth routes:
```
@include('ti-ext-user::auth.register')
```
Check authentication with the package/auth guard:
```
use TastyIgniter\TiExtUser\Facades\Auth;

if (Auth::check()) {
    // User is logged in
}
```
Admin access: Log in to /admin and use Users > Customers or Users > Staff to manage accounts through the built-in UI. In v4.2.1, customer search/filtering can use first_name, last_name, email, and telephone where the model query modifier is used.
Quick search smoke test: Confirm the new searchable fields work in the admin customer list or any package-backed list that uses the Customer query modifier:
```
use TastyIgniter\TiExtUser\Models\Customer;

$customers = Customer::query()
    ->search('jane')
    ->get();
```

Where to Look First

Model changes: Inspect src/Models/Customer.php for the newly declared searchable fields: first_name, last_name, email, telephone.
Documentation: TastyIgniter User extension docs for setup and auth references.
Views: /resources/views/vendor/ti-ext-user/ for auth forms and email templates.
Events: /src/Events/ for lifecycle hooks such as UserRegistered and UserLoggedIn.
Middleware: /src/Http/Middleware/ for customer/admin auth behavior.
Requests/validation: Check the user form request/controller path when overriding admin user forms, especially around sale_permission.

Implementation Patterns

Usage Patterns

1. Frontend authentication

Use the package Blade components or your own controllers with the package models:

@auth
    <p>Welcome, {{ Auth::user()->name }}!</p>
@else
    @include('ti-ext-user::auth.login')
@endauth

Custom validation can extend the package request:

namespace App\Http\Requests;

use TastyIgniter\TiExtUser\Http\Requests\CustomerRequest as BaseCustomerRequest;

class CustomerRequest extends BaseCustomerRequest
{
    public function rules()
    {
        return array_merge(parent::rules(), [
            'custom_field' => 'required|string',
        ]);
    }
}

2. Creating customers and assigning roles

use TastyIgniter\TiExtUser\Models\Customer;

$customer = Customer::create([
    'email' => '[email protected]',
    'password' => bcrypt('password123'),
    'first_name' => 'John',
    'last_name' => 'Doe',
    'status' => true,
]);

$customer->assignRole('customer');

3. Customer search and lookup

The v4.2.1 Customer model declares searchable fields for the package query modifier:

use TastyIgniter\TiExtUser\Models\Customer;

$matches = Customer::query()
    ->search('555-0100')
    ->get();

This is most useful for admin customer lists and package-backed filters. For direct field lookups, plain Eloquent remains fine:

$customer = Customer::where('email', $email)->first();

4. Guest order claiming

v4.2.1 fixes guest order claiming for legacy rows where customer_id is 0. The claim lookup now scopes by email, preventing a legacy guest-order row from matching the wrong customer. When integrating registration/login with order history, keep the claim flow keyed to the same email address used on the order:

$customer = Customer::where('email', $request->email)->first();

// The package's claiming flow should now correctly handle legacy customer_id = 0 rows
// by matching on email, not by treating 0 as a wildcard.

Do not write custom blanket updates such as where('customer_id', 0)->update(...); scope legacy guest-order claiming by email.

5. Saving user forms and `sale_permission`

v4.2.1 adds the missing sale_permission validation rule. If you override or replace the admin user form request, preserve that rule:

public function rules()
{
    return array_merge(parent::rules(), [
        // your custom rules
    ]);
}

Ensure the field is present in the submitted payload and allowed by your form. Without the rule, the permission value may not be validated or stored correctly.

6. Impersonation

Admins can impersonate users for debugging:

use TastyIgniter\TiExtUser\Facades\Auth;

$customer = \TastyIgniter\TiExtUser\Models\Customer::find(1);
Auth::impersonate($customer);

// Later
Auth::endImpersonation();

7. Events and listeners

Hook into lifecycle events for onboarding or auditing:

use TastyIgniter\TiExtUser\Events\UserRegistered;

UserRegistered::listen(function (UserRegistered $event) {
    \Log::info("New user registered: {$event->user->email}");
});

8. API authentication

Use the package models with your API auth stack:

use Illuminate\Support\Facades\Hash;
use TastyIgniter\TiExtUser\Models\Customer;

$customer = Customer::where('email', $request->email)->first();

if ($customer && Hash::check($request->password, $customer->password)) {
    $token = $customer->createToken('auth_token')->plainTextToken;

    return response()->json(['token' => $token]);
}

Workflows

Customer onboarding

User submits registration at /register.
UserRegistered fires; send welcome email or trigger automation.
If email verification is enabled, the user verifies before full access.
User logs in and is redirected to account/order/profile pages.

Guest order claim after registration

Guest places an order with an email address.
Guest registers or logs in using the same email.
The package claims matching guest orders. In v4.2.1, legacy rows with customer_id = 0 are scoped by email, so a guest order is not claimed by an unrelated customer.
Verify that historical rows have usable email values before relying on the claim flow.

Staff management

Admin creates staff via /admin/users/staff.
Staff logs in to restricted areas.
Admin impersonates staff for support/debugging, then ends impersonation.

Password reset

User requests reset via /forgot-password.
Reset event sends the link.
User submits a new password via /reset-password.
Token expiry is controlled in config/ti-ext-user.php.

Integration Tips

Override email templates by publishing/copying package views into resources/views/ti-ext-user/emails/.

Extend models if you add custom columns:

namespace App\Models;

use TastyIgniter\TiExtUser\Models\Customer as BaseCustomer;

class Customer extends BaseCustomer
{
    protected $casts = [
        // merge or define custom casts carefully
    ];
}

Customize auth behavior by publishing package auth assets and extending the service provider or guard logic.
Localization: publish translations and add language files under resources/lang/.
Admin forms: when adding fields to the user form, validate sale_permission along with your custom fields so permission changes are persisted.

Gotchas and Tips

Pitfalls

Searchable fields are not full-text search
- v4.2.1 adds first_name, last_name, email, and telephone as searchable fields for the package query modifier.
- Do not assume this changes plain Eloquent behavior. Direct where() queries still require explicit column names and matching strategy.
Guest order claiming behavior changed for legacy rows
- Rows with customer_id = 0 are now scoped by email during claiming.
- If you maintained custom code that treated customer_id = 0 as “unclaimed for anyone,” update it to match the package’s email-scoped behavior.
- Check email normalization (trim/lowercase) if your own order-import or registration code writes inconsistent email values.
Missing sale_permission rule in custom user forms
- v4.2.1 fixes the missing validation rule. If you copied or overrode the user form request before this release, your copy may still omit it.
- Merge parent rules or explicitly add sale_permission validation so permission changes are stored.
Permission/role caching
- Permission changes may not appear immediately. Clear caches after role or permission updates:
```
php artisan cache:clear
php artisan optimize:clear
```
- Refresh the user model or permission cache if your integration caches authorization results.
Impersonation session conflicts
- Impersonation can behave unexpectedly if another guard/session is already active.
- Test in a fresh session and always exit impersonation:
```
Auth::impersonate($user);
// debug work
Auth::endImpersonation();
```
Email verification and mail configuration
- If verification emails fail silently, check failed_jobs, application logs, and .env mail settings:
```
MAIL_MAILER=smtp
MAIL_FROM_ADDRESS=...
```
- Queue workers must be running if verification mail is queued.
Password reset token expiry
- Default expiry is typically 60 minutes. Confirm and adjust in config/ti-ext-user.php:
```
'password_reset' => [
    'expire' => 60,
],
```
Migration conflicts
- Review package migrations before running php artisan igniter:up in an existing database, especially if you have custom user/customer columns.
- Back up the database before applying migrations in production.
Overriding package requests/controllers
- Prefer extending package classes and merging parent rules. Replacing them wholesale can drop fixes such as the v4.2.1 sale_permission rule or future validation changes.

Debugging

Events: temporarily listen for user lifecycle events in a service provider:

use Illuminate\Support\Facades\Event;
use TastyIgniter\TiExtUser\Events\UserRegistered;

Event::listen(UserRegistered::class, function (UserRegistered $event) {
    logger()->debug('User registered', [
        'id' => $event->user->id,
        'email' => $event->user->email,
    ]);
});

Search/filter issues: confirm the list is using the package query modifier and that the search term matches one of the v4.2.1 searchable fields.
Guest order claim issues: inspect the order’s customer_id and email, then confirm the customer email matches exactly. Legacy rows with customer_id = 0 should be claimed only through the email-scoped path.
User form permission not saving: log the validated payload and confirm sale_permission is present, validated, and allowed by the form/configuration.

Clear caches after upgrades:

php artisan optimize:clear
composer dump-autoload

Check logs in storage/logs/laravel.log and queue failure tables when notifications or verification emails are not delivered.

Ti Ext User Laravel Package