Getting Started

Minimal Steps

Install the Package
```
composer require baks-dev/users-address
```
Ensure your composer.json supports PHP 8.4+ and Laravel 10.x.
Publish Assets and Config Run the Artisan command to install migrations, views, and configurations:
```
php artisan baks:assets:install
```
This generates:
- Database migrations (database/migrations/).
- Configuration files (config/users-address.php).
- Optional views (resources/views/vendor/users-address/).
Run Migrations Generate and apply the schema changes:
```
php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate
```
Verify the users_addresses table and related entities exist.

First Use Case: Create a User with an Address Use the package’s Address entity to attach addresses to users:

use Baks\UsersAddress\Models\Address;
use Baks\UsersAddress\Models\User; // Assuming extended User model

$user = User::find(1);
$user->addresses()->create([
    'type' => 'home', // e.g., 'home', 'work', 'billing'
    'street' => '123 Main St',
    'city' => 'Springfield',
    'postal_code' => '12345',
    'country' => 'US',
]);

Save the user to persist the address.

Implementation Patterns

Core Workflows

1. User-Address Relationships

One-to-Many: A user can have multiple addresses (e.g., home, work, billing).

// Define in User model (Doctrine)
/**
 * @ORM\OneToMany(targetEntity="Baks\UsersAddress\Models\Address", mappedBy="user")
 */
private Collection $addresses;

Default Address: Mark one address as default for operations (e.g., checkout).

$user->setDefaultAddress($address);
$defaultAddress = $user->getDefaultAddress();

2. Validation and Geocoding

Built-in Validation: The package validates address formats (e.g., country-specific rules).

$validator = \Baks\UsersAddress\Validators\AddressValidator::validate($data);
if ($validator->fails()) {
    // Handle errors
}

Geocoding Integration: Use a service provider to plug in geocoding APIs (e.g., Google Maps, OpenStreetMap).

// Configure in config/users-address.php
'geocoding' => [
    'provider' => 'google',
    'api_key' => env('GOOGLE_MAPS_API_KEY'),
];

// Trigger geocoding
$address->geocode();

3. CRUD Operations

Create/Update:

$address = $user->addresses()->create($validatedData);
$address->update(['street' => 'New Address']);

Delete:

$address->delete(); // Soft delete if configured

4. Multi-Address Scenarios

Address Types: Use type field (e.g., home, work) to categorize addresses.

$billingAddress = $user->addresses()->where('type', 'billing')->first();

Default Address Logic:

// Set default address
$user->addresses()->where('type', 'home')->update(['is_default' => false]);
$newDefault = $user->addresses()->where('type', 'work')->first();
$newDefault->setAsDefault();

5. API/Endpoint Integration

RESTful Resources: If the package includes routes, register them in routes/web.php:

Route::apiResource('user-addresses', \Baks\UsersAddress\Http\Controllers\AddressController::class);

Custom Endpoints: Extend controllers or create middleware for address-specific logic:

// Example: Middleware to validate address on checkout
public function handle(Request $request, Closure $next) {
    $address = $request->user()->getDefaultAddress();
    if (!$address || !$address->isValid()) {
        abort(422, 'Invalid address for checkout.');
    }
    return $next($request);
}

Integration Tips

Doctrine vs. Eloquent:

If your app uses Eloquent, create a compatibility layer or extend the package’s entities:

// Example: Eloquent-compatible Address model
class EloquentAddress extends \Illuminate\Database\Eloquent\Model {
    protected $fillable = ['user_id', 'type', 'street', 'city', ...];

    public function user() {
        return $this->belongsTo(User::class);
    }
}

Use Doctrine’s EntityManager to bridge models:

$em = app(\Doctrine\ORM\EntityManagerInterface::class);
$address = $em->find(Address::class, $id);

Event-Driven Extensions:

Listen to address events for custom logic (e.g., notifications, analytics):

use Baks\UsersAddress\Events\AddressCreated;

AddressCreated::listen(function ($event) {
    \Log::info("New address created for user {$event->user->id}");
    // Send welcome email or trigger geocoding
});

Testing:

Run package-specific tests:
```
php artisan test --group=users-address
```

Write feature tests for your integration:

public function test_user_can_add_address() {
    $user = User::factory()->create();
    $this->actingAs($user);
    $response = $this->post('/user-addresses', [
        'type' => 'home',
        'street' => '123 Test St',
        // ...
    ]);
    $response->assertCreated();
}

Localization:

Override validation messages or address fields in config/users-address.php:

'validation' => [
    'messages' => [
        'street.required' => 'The street field is required.',
        'country.in' => 'The selected country is invalid.',
    ],
],

Geocoding Providers:

Implement a custom geocoding service by extending the base provider:

namespace App\Services;

use Baks\UsersAddress\Contracts\GeocodingService;

class CustomGeocodingService implements GeocodingService {
    public function geocode($address) {
        // Integrate with your API
        return ['lat' => 12.34, 'lng' => 56.78];
    }
}

Bind it in a service provider:

$this->app->bind(GeocodingService::class, CustomGeocodingService::class);

Gotchas and Tips

Pitfalls

Doctrine ORM Dependency:
- Issue: The package uses Doctrine entities, which may conflict with Eloquent models or apps not using Doctrine.
- Fix: Use a compatibility layer or stick to Doctrine for the address module. Avoid mixing ORMs in the same entity.
Migration Conflicts:
- Issue: If your app already has an addresses table or related migrations, conflicts may arise.
- Fix:
  - Review the generated migration (doctrine:migrations:diff) before applying.
  - Use --down migrations to roll back if needed:
```
php artisan doctrine:migrations:execute --down
```
  - Manually merge schemas if tables overlap.
Geocoding API Dependencies:
- Issue: Geocoding requires third-party APIs (e.g., Google Maps), which may have rate limits or costs.
- Fix:
  - Use a free tier (e.g., OpenStreetMap) for development.
  - Implement caching to avoid repeated API calls:
```
$geocodedData = cache()->remember("geocode_{$address->hash}", now()->addHours(1), function () {
    return $address->geocode();
});
```

Address Validation Overrides:

Issue: Default validation rules may not fit all countries or use cases (e.g., non-Latin scripts).

Fix: Extend the validator or override rules:

// Override in a service provider
$validator = new \Baks\UsersAddress\Validators\AddressValidator();
$validator->setRules([
    'country' => 'required|in:US,CA,JP,IN', // Custom list
    'postal_code' => 'required|regex:/^[A-Z0-9]{5}$/', // US-specific
]);

Performance with Large Address Books:
- Issue: Fetching all addresses for a user with many entries can be slow.
- **Fix

Users Address Laravel Package