Reloadly Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ghanem/reloadly
   php artisan vendor:publish --provider="Ghanem\Reloadly\ReloadlyServiceProvider" --tag="config"
   

   Configure .env with your Reloadly API credentials:

   RELOADLY_API_KEY=your_api_key
   RELOADLY_API_SECRET=your_api_secret
   

2. First Use Case: Fetch countries to validate a user's input (e.g., in a form):

   use Ghanem\Reloadly\Facades\Reloadly;
   
   $countries = Reloadly::countries(); // Returns array of country data
   

Where to Look First

• Facade Methods: Check the README for available methods (e.g., countries(), countryByIsoCode()).
• Config File: Published at config/reloadly.php—adjust API endpoints or defaults if needed.
• Service Provider: Extend functionality by binding additional services in ReloadlyServiceProvider.

Implementation Patterns

Common Workflows

1. Data Validation: Use Reloadly::countryByIsoCode() to validate country codes in registration forms:

   $country = Reloadly::countryByIsoCode(request('country_code'));
   if (!$country) abort(422, 'Invalid country code');
   

2. Operator Lookup: Fetch mobile operators for a country to pre-populate dropdowns:

   $operators = Reloadly::operators('eg'); // Operators for Egypt
   

3. Integration with Eloquent: Attach country/operator data to models via accessors:

   // In User model
   public function getCountryNameAttribute() {
       return Reloadly::countryByIsoCode($this->country_code)?->name ?? null;
   }
   

4. API Rate Limiting: Cache responses for static data (e.g., countries) to avoid hitting Reloadly’s API limits:

   $countries = Cache::remember('reloadly_countries', now()->addHours(1), function() {
       return Reloadly::countries();
   });
   

Integration Tips

• Service Layer: Wrap Reloadly calls in a service class to abstract API logic:

  class CountryService {
      public function getValidCountries() {
          return Reloadly::countries()->map(fn($c) => ['value' => $c->iso_code, 'label' => $c->name]);
      }
  }
  

• Error Handling: Use Laravel’s try-catch to handle API failures gracefully:

  try {
      $data = Reloadly::someMethod();
  } catch (\Ghanem\Reloadly\Exceptions\ReloadlyException $e) {
      Log::error($e->getMessage());
      abort(503, 'Service unavailable');
  }
  

• Testing: Mock the facade in unit tests:

  $this->mock(Reloadly::class)->shouldReceive('countries')->andReturn([...]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods: The package is outdated (last release 2021). Some Reloadly API endpoints may have changed. Verify endpoints in config/reloadly.php match Reloadly’s current docs.

2. Authentication Issues:

   • Ensure RELOADLY_API_KEY and RELOADLY_API_SECRET are correct.
   • If using a proxy or load balancer, ensure headers (e.g., X-API-KEY) are forwarded.

3. Rate Limits: Reloadly’s API has strict rate limits. Cache responses aggressively for static data (e.g., countries).

4. GIFs Feature: The README mentions "includes Gifs," but this isn’t documented. Avoid relying on undocumented features.

Debugging

• Enable API Logging: Add to config/reloadly.php:

  'debug' => env('RELOADLY_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Check HTTP Status Codes: Wrap calls in try-catch to log Reloadly’s response status:

  try {
      $response = Reloadly::someMethod();
  } catch (\Ghanem\Reloadly\Exceptions\HttpException $e) {
      Log::error('Reloadly API Error: ' . $e->getResponse()->status());
  }
  

Extension Points

1. Custom Endpoints: Override the base URL in config/reloadly.php:

   'api_url' => env('RELOADLY_API_URL', 'https://api.reloadly.com/v1'),
   

2. Add New Methods: Extend the facade by binding a custom service:

   // In a service provider
   $this->app->bind('reloadly.custom', function() {
       return new \App\Services\ReloadlyCustomService();
   });
   

   Then use it via the facade:

   Reloadly::customMethod();
   

3. Webhook Handling: The package doesn’t support webhooks. For real-time updates, use Laravel’s queue:work with Reloadly’s webhook URLs and validate signatures manually.

Tips

• Use reloadly:clear-cache Artisan Command: If the package includes one, clear cached API responses during deployment:

  php artisan reloadly:clear-cache
  

• Laravel 10+ Compatibility: The package targets Laravel 8.x. For newer versions, update dependencies in composer.json or fork the package.
• Document Assumptions: Since the package is minimal, document any assumptions (e.g., "We assume Reloadly’s /countries endpoint returns ISO codes").