Getting Started

Minimal Setup Steps

Install the Package

composer require baks-dev/contacts-region

Publish Configuration and Assets Run the package’s installation command to set up initial configuration and resources:
```
php artisan baks:assets:install
```
Note: If using Laravel, ensure the baks:assets:install command is registered in app/Console/Kernel.php or wrapped in an Artisan command.
Run Database Migrations Generate and apply migrations to set up the required tables:
```
php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate
```
For Laravel users, consider using doctrine/dbal or converting migrations to Laravel’s format.

First Use Case: Create a Regional Contact Use the package’s repository or service to create a contact tied to a region:

use BaksDev\ContactsRegion\Repository\ContactRepository;

$contactRepository = app(ContactRepository::class);
$contact = $contactRepository->create([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'region_id' => 1, // Assuming region_id is defined in baks-dev/reference-region
    'phone' => '+1234567890',
]);

Verify Installation Check the database for new tables (e.g., contact, region_contact) and test CRUD operations via Tinker or a simple route:
```
php artisan tinker
>>> $contactRepository->find(1);
```

Implementation Patterns

Core Workflows

1. Regional Contact Management

Create/Update Contacts: Use the ContactRepository or a dedicated service to handle regional contacts. Example:

$service = app(\BaksDev\ContactsRegion\Service\ContactService::class);
$service->createOrUpdate($regionId, $contactData);

Query Contacts by Region: Leverage the repository’s built-in methods or create custom queries:
```
$contacts = $contactRepository->findByRegion($regionId, ['name', 'email']);
```

2. Asset and Configuration Handling

Install/Update Assets: Re-run the installation command to refresh regional assets (e.g., templates, uploads):
```
php artisan baks:assets:install
```
Custom Asset Paths: Override default paths in the package’s configuration (published via baks:assets:install):
```
'asset_paths' => [
    'regional_templates' => storage_path('app/regional-templates'),
],
```

3. Integration with Existing Systems

Laravel Eloquent Bridge: Extend the package’s entities to use Eloquent by creating a trait or abstract class:

use Illuminate\Database\Eloquent\Model;

abstract class RegionalContactModel extends Model {
    protected $table = 'contact';
    // Override methods as needed
}

Event Listeners: Subscribe to package events (if supported) or create custom listeners for regional contact actions:
```
use BaksDev\ContactsRegion\Event\ContactCreated;

event(new ContactCreated($contact));
```
Note: If using Symfony’s EventDispatcher, wrap it in Laravel’s event system or use a facade.

4. Validation and Business Logic

Custom Validation Rules: Extend the package’s validation logic by creating a form request or validator:

use Illuminate\Validation\Rule;

$validator = Validator::make($data, [
    'email' => ['required', Rule::unique('contact')->where('region_id', $regionId)],
]);

Regional-Specific Rules: Use conditional validation based on region (e.g., phone format validation per country):
```
$rules = $region->phone_format_rules; // Assume this is fetched from the region
```

5. Testing

Unit Tests: Run package-specific tests:

php artisan test --group=contacts-region

Feature Tests: Test regional contact workflows in Laravel’s testing environment:

public function test_create_regional_contact()
{
    $response = $this->post('/contacts', [
        'region_id' => 1,
        'name' => 'Test Contact',
    ]);
    $response->assertCreated();
}

Integration Tips

Laravel-Specific Adjustments

Service Provider Setup: Register the package’s services in AppServiceProvider:

public function register()
{
    $this->app->bind(
        \BaksDev\ContactsRegion\Repository\ContactRepository::class,
        \BaksDev\ContactsRegion\Laravel\ContactRepository::class
    );
}

Doctrine to Eloquent: Create a Laravel-compatible repository interface:

namespace App\Repositories;

interface ContactRepositoryInterface {
    public function findByRegion(int $regionId, array $fields = []);
}

Console Commands: Wrap Symfony commands in Artisan commands. Example:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Console\Application;

class InstallAssetsCommand extends Command {
    protected $signature = 'baks:assets:install';
    public function handle() {
        $symfonyApp = new Application();
        $symfonyApp->find('baks:assets:install')->run(new \Symfony\Component\Console\Input\ArrayInput([]), new \Symfony\Component\Console\Output\ConsoleOutput());
    }
}

Extending Functionality

Custom Contact Fields: Add fields via database migrations and update the package’s entity mapper:

// In a migration
Schema::table('contact', function (Blueprint $table) {
    $table->string('custom_field')->nullable();
});

// Extend the entity
class ExtendedContact extends \BaksDev\ContactsRegion\Entity\Contact {
    public ?string $customField;
}

Regional Contact Search: Add a custom query builder method to the repository:

public function searchByName(string $name, int $regionId): array {
    return $this->createQueryBuilder('c')
        ->where('c.region_id = :regionId')
        ->andWhere('c.name LIKE :name')
        ->setParameter('regionId', $regionId)
        ->setParameter('name', "%{$name}%")
        ->getQuery()
        ->getResult();
}

API Endpoints: Create Laravel routes and controllers for regional contacts:

Route::apiResource('regions.{region}/contacts', \App\Http\Controllers\RegionalContactController::class);

Gotchas and Tips

Pitfalls and Debugging

1. Symfony-Laravel Integration Issues

Symfony Console Commands: Issue: Commands like baks:assets:install may fail due to missing Symfony dependencies. Fix: Install the Symfony Console component or wrap commands in Artisan as shown above.
Dependency Conflicts: Issue: Version conflicts between Symfony components (e.g., symfony/console, symfony/dependency-injection) and Laravel’s dependencies. Fix: Use composer why-not to diagnose conflicts and override versions in composer.json:
```
"extra": {
    "laravel": {
        "dont-discover": ["baks-dev/contacts-region"]
    }
}
```

2. Database Migrations

Doctrine vs. Laravel Migrations: Issue: Doctrine migrations may not work seamlessly with Laravel’s migration system. Fix: Convert Doctrine migrations to Laravel format or use a hybrid approach with doctrine/dbal.
Schema Mismatches: Issue: The package’s migrations may assume a schema that conflicts with existing tables. Fix: Review the migration files in vendor/baks-dev/contacts-region/migrations/ and adjust or extend them.

3. Regional Data Model

Reference Region Dependency: Issue: The package relies on baks-dev/reference-region for regional data (e.g., region_id). Fix: Ensure your regional data model matches the package’s expectations. If not, create a mapping layer or extend the reference region package.
Missing Regional Hierarchy: Issue: The package may expect a specific regional hierarchy (e.g., country → state → city) that doesn’t exist in your system. Fix: Customize the reference-region package or build a compatibility layer.

4. Asset Management

File Path Assumptions: Issue: The baks:assets:install command may assume specific file paths (e.g., public/regional-assets). Fix: Override paths in the package’s configuration

Contacts Region Laravel Package