Http Statuses Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel-lang/http-statuses
   

   Publish translations (if needed):

   php artisan vendor:publish --provider="LaravelLang\HttpStatuses\ServiceProvider"
   

2. First Use Case: Display a translated HTTP status message in a controller or Blade template:

   use LaravelLang\HttpStatuses\Facades\HttpStatuses;
   
   $status = HttpStatuses::get(404); // Returns "Not Found" in the current locale
   return response()->json(['error' => $status], 404);
   

3. Where to Look First:

   • Facade: LaravelLang\HttpStatuses\Facades\HttpStatuses
   • JSON Structure: Published translations are stored in resources/lang/{locale}/http-statuses.json
   • Documentation: Laravel Lang HTTP Statuses Docs

Implementation Patterns

Core Workflows

1. Dynamic Status Messages:

   // In a controller or service
   $message = HttpStatuses::get($httpStatusCode);
   return response()->json(['message' => $message], $httpStatusCode);
   

2. Blade Integration:

   @php
       $status = LaravelLang\HttpStatuses\Facades\HttpStatuses::get($responseStatus);
   @endphp
   <p>{{ $status }}</p>
   

3. API Responses:

   return response()->json([
       'success' => false,
       'message' => HttpStatuses::get(429),
       'retry_after' => now()->addMinutes(5)
   ], 429);
   

4. Custom Error Pages:

   // app/Exceptions/Handler.php
   public function render($request, Throwable $exception)
   {
       if ($exception instanceof HttpResponseException) {
           $status = HttpStatuses::get($exception->getStatusCode());
           return response()->view('errors.custom', [
               'status' => $status,
               'exception' => $exception
           ], $exception->getStatusCode());
       }
       return parent::render($request, $exception);
   }
   

Integration Tips

• Localization: Automatically respects the app's current locale (configured in AppServiceProvider).
• Fallbacks: Missing translations fall back to the default English (en) translations.
• Testing: Use the facade directly in unit tests:

  $this->assertEquals('Not Found', HttpStatuses::get(404));
  

Gotchas and Tips

Pitfalls

1. Locale Mismatches:

   • Ensure your app's locale is set before calling HttpStatuses::get().
   • Debug with:

     app()->setLocale('es'); // Force locale for testing
     

2. Missing Translations:

   • Some locales may have incomplete translations (e.g., machine-translated ones).
   • Check the GitHub issues for known gaps.

3. Caching:

   • Translations are cached by Laravel’s default mechanism. Clear cache if translations don’t update:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

• Inspect Translations:

  // Dump all available translations for a locale
  dd(HttpStatuses::all('es'));
  

• Override Translations: Publish and modify the JSON files in resources/lang/{locale}/http-statuses.json:

  php artisan vendor:publish --tag=http-statuses --force
  

Extension Points

1. Add Custom Status Codes: Extend the package by publishing and modifying the JSON files, or create a custom service:

   use Illuminate\Support\Facades\File;
   
   class CustomHttpStatuses extends \LaravelLang\HttpStatuses\Facades\HttpStatuses
   {
       public static function get($code)
       {
           $customStatuses = [
               999 => 'Custom Status Message',
           ];
           return $customStatuses[$code] ?? parent::get($code);
       }
   }
   

2. Dynamic Context: Use Laravel’s translation system to pass context:

   __('http-statuses::403', [], 'es'); // Directly use the JSON key
   

3. Performance: For high-traffic APIs, preload translations in a service provider:

   public function boot()
   {
       app()->singleton('http-statuses', function () {
           return collect(HttpStatuses::all())->mapWithKeys(fn ($messages, $locale) => [
               $locale => collect($messages)->map(fn ($msg, $code) => [
                   'code' => $code,
                   'message' => $msg,
               ]),
           ]);
       });
   }