Pando Contact Info Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require blackboxcode/pando-contact-info-bundle
   

   Register the bundle in config/app.php under providers:

   BlackBoxCode\PandoContactInfoBundle\PandoContactInfoBundle::class,
   

2. Publish Configuration Publish the default config to customize behavior:

   php artisan vendor:publish --provider="BlackBoxCode\PandoContactInfoBundle\PandoContactInfoBundle" --tag="config"
   

   Locate the config file at config/pando_contact_info.php.

3. First Use Case: Displaying Contact Info Inject the ContactInfoService into a controller or service:

   use BlackBoxCode\PandoContactInfoBundle\Services\ContactInfoService;
   
   class ContactController extends Controller
   {
       protected $contactInfo;
   
       public function __construct(ContactInfoService $contactInfo)
       {
           $this->contactInfo = $contactInfo;
       }
   
       public function show()
       {
           $contactData = $this->contactInfo->getAll();
           return view('contact', compact('contactData'));
       }
   }
   

4. Basic Configuration Define contact details in config/pando_contact_info.php:

   'contact' => [
       'email' => 'contact@example.com',
       'phone' => '+1 (555) 123-4567',
       'address' => '123 Main St, City, Country',
       'hours' => 'Mon-Fri: 9AM-5PM',
   ],
   

Implementation Patterns

Core Workflows

1. Fetching Contact Data Use the ContactInfoService to retrieve contact details:

   $email = $this->contactInfo->getEmail(); // Returns 'contact@example.com'
   $phone = $this->contactInfo->getPhone(); // Returns '+1 (555) 123-4567'
   $allData = $this->contactInfo->getAll(); // Returns associative array of all contact info
   

2. Dynamic Contact Info via Providers Extend functionality by creating custom providers. Implement the ContactInfoProviderInterface:

   namespace App\Providers;
   
   use BlackBoxCode\PandoContactInfoBundle\Contracts\ContactInfoProviderInterface;
   
   class SocialMediaProvider implements ContactInfoProviderInterface
   {
       public function getContactInfo(): array
       {
           return [
               'social_media' => [
                   'twitter' => '@company',
                   'facebook' => 'company.page',
               ],
           ];
       }
   }
   

   Register the provider in config/pando_contact_info.php:

   'providers' => [
       App\Providers\SocialMediaProvider::class,
   ],
   

3. Localization Support Override contact info per locale by publishing translations:

   php artisan vendor:publish --provider="BlackBoxCode\PandoContactInfoBundle\PandoContactInfoBundle" --tag="translations"
   

   Update resources/lang/{locale}/contact.php:

   return [
       'email' => 'kontakt@beispiel.de',
       'phone' => '+49 (30) 12345678',
   ];
   

4. Integration with Forms Use the bundle to pre-fill contact forms or validate submissions:

   // In a FormRequest
   public function rules()
   {
       return [
           'email' => 'required|email:rfc,dns,spoof|max:255|sometimes',
       ];
   }
   
   public function messages()
   {
       return [
           'email.required' => 'Please use our contact email: ' . $this->contactInfo->getEmail(),
       ];
   }
   

Advanced Patterns

1. Caching Contact Data Enable caching in config/pando_contact_info.php:

   'cache' => [
       'enabled' => true,
       'ttl' => 3600, // Cache for 1 hour
   ],
   

   Clear cache when contact info updates:

   php artisan cache:clear
   

2. API Endpoints Create a dedicated API resource:

   namespace App\Http\Resources;
   
   use BlackBoxCode\PandoContactInfoBundle\Services\ContactInfoService;
   use Illuminate\Http\Resources\Json\JsonResource;
   
   class ContactInfoResource extends JsonResource
   {
       public function __construct(ContactInfoService $contactInfo)
       {
           parent::__construct($contactInfo->getAll());
       }
   
       public function toArray($request)
       {
           return $this->resource;
       }
   }
   

   Route it in routes/api.php:

   Route::get('/contact', [ContactController::class, 'api'])->name('contact.api');
   

3. Frontend Integration (Blade Directives) Create a custom Blade directive for reusable contact info:

   // In AppServiceProvider@boot()
   Blade::directive('contact', function ($expression) {
       $contactInfo = app('contactInfo');
       return "<?php echo \$contactInfo->{$expression}(); ?>";
   });
   

   Usage in Blade:

   <p>Email: @contact('getEmail')</p>
   

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides

   • Issue: Custom providers or translations may not load if the config is not published or updated.
   • Fix: Always run php artisan config:clear after publishing config or translations.
   • Tip: Use php artisan config:cache in production to avoid runtime overrides.

2. Caching Conflicts

   • Issue: Changes to contact info (e.g., via providers) may not reflect immediately if caching is enabled.
   • Fix: Disable caching during development ('cache' => ['enabled' => false]).
   • Debug: Check cached data with php artisan cache:table and inspect the cache table.

3. Locale Fallbacks

   • Issue: Missing translations for a locale may cause errors.
   • Fix: Ensure all locales have a contact.php file, even if empty. Use Laravel’s fallback locales:

     'fallback_locales' => ['en'],
     

4. Provider Loading Order

   • Issue: Providers may override each other unpredictably.
   • Fix: Define an explicit order in config/pando_contact_info.php:

     'providers' => [
         App\Providers\SocialMediaProvider::class,
         App\Providers\LegalInfoProvider::class,
     ],
     

Debugging Tips

1. Log Contact Data Add a temporary debug method to ContactInfoService:

   public function debug()
   {
       \Log::debug('Contact Info:', $this->getAll());
   }
   

   Call it in a route or controller for quick inspection.

2. Check Provider Execution Temporarily add logging to providers:

   public function getContactInfo(): array
   {
       \Log::info('SocialMediaProvider executed');
       return [...];
   }
   

3. Validate Config Structure Use Laravel’s config validation:

   $this->validateConfigStructure();
   

   Add this method to ContactInfoService to ensure required keys exist.

Extension Points

1. Custom Contact Fields Extend the base config structure by creating a custom provider:

   class CustomFieldsProvider implements ContactInfoProviderInterface
   {
       public function getContactInfo(): array
       {
           return [
               'custom' => [
                   'support_ticket' => 'https://support.example.com',
                   'chat' => 'https://chat.example.com',
               ],
           ];
       }
   }
   

2. Dynamic Data Sources Fetch contact info from an external API:

   class ApiContactProvider implements ContactInfoProviderInterface
   {
       public function getContactInfo(): array
       {
           $response = Http::get('https://api.example.com/contact');
           return $response->json();
       }
   }
   

3. Event Listeners Trigger events when contact info is accessed or updated:

   // In EventServiceProvider@boot()
   ContactInfoService::getAll(function ($contactInfo) {
       event(new ContactInfoRetrieved($contactInfo));
   });
   

4. Testing Mock the ContactInfoService in tests:

   $mockContactInfo = Mockery::mock(ContactInfoService::class);
   $mockContactInfo->shouldReceive('getEmail')->andReturn('test@example.com');
   
   $this->app->instance(ContactInfoService::class, $mockContactInfo);