Data Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require moox/data
   php artisan data:install
   

   • The data:install command publishes config, migrations, and assets.

2. First Use Case: Access static data via the Data facade:

   use Moox\Data\Facades\Data;
   
   $countries = Data::countries(); // Returns collection of country data
   $languages = Data::languages(); // Returns collection of language data
   

3. Frontend Integration: Use the provided Livewire component for language switching:

   <livewire:language-switch />
   

   • Defaults to frontend context; specify otherwise via component props.

Implementation Patterns

Core Usage Patterns

1. Data Retrieval:

   // Get all countries with ISO codes
   $countries = Data::countries()->pluck('iso_code', 'name');
   
   // Get timezone data for a specific country
   $timezones = Data::timezones()->where('country', 'US');
   

2. Integration with Eloquent:

   use Moox\Data\Concerns\HasCountries;
   
   class User extends Model
   {
       use HasCountries;
   
       protected $countryData;
   }
   
   // Automatically loads country data for the user's country
   $user->loadCountryData();
   

3. Dynamic Tabs (Admin Panel): Enable in config/moox-data.php:

   'tabs' => [
       'countries' => 'Countries',
       'languages' => 'Languages',
       'timezones' => 'Timezones',
       'currencies' => 'Currencies',
   ],
   

   • Tabs auto-render in the /data panel (if enable-panel is true).

4. Translation Handling: Override default labels in config:

   'translations' => [
       'countries' => [
           'name' => 'Country Name',
           'iso_code' => 'ISO Code',
       ],
   ],
   

Workflows

1. Localization Workflow:

   • Use Data::languages() to populate a dropdown in a form.
   • Store user-preferred language in a preferred_language column.
   • Retrieve translated labels via Data::translate('countries.name').

2. Multi-Tenant Timezone Handling:

   $tenantTimezone = Data::timezones()
       ->where('country', $tenant->country_code)
       ->first()
       ->timezone;
   

3. Currency Conversion:

   $usdToEurRate = Data::currencies()
       ->where('code', 'USD')
       ->first()
       ->rate_to('EUR');
   

Gotchas and Tips

Pitfalls

1. Panel Route Conflict:

   • The /data panel route may conflict with existing routes.
   • Fix: Override the panel route in config:

     'panel_route' => 'admin/data',
     

2. Livewire Component Context:

   • The language-switch component defaults to frontend context.
   • Fix: Pass context='admin' if used in backend:

     <livewire:language-switch context="admin" />
     

3. Data Updates:

   • Static data is published via migrations. Manual updates require:

     php artisan data:update
     

   • Tip: Extend the DataServiceProvider to fetch updates from an API if needed.

4. Translation Overrides:

   • Overriding translations in config only affects the panel, not the facade.
   • Workaround: Use a custom facade binding:

     Data::macro('translate', function ($key, $locale = null) {
         return trans("moox-data::{$key}", [], $locale);
     });
     

Debugging

1. Missing Data:

   • Check if migrations ran:

     php artisan migrate:status
     

   • Reinstall data:

     php artisan data:install --force
     

2. Livewire Component Errors:

   • Ensure moox/data is listed in composer.json under require.
   • Clear Livewire cache:

     php artisan livewire:discover
     

Extension Points

1. Custom Data Sources:

   • Extend the DataService class to fetch data from external APIs:

     namespace App\Services;
     
     use Moox\Data\Services\DataService;
     
     class CustomDataService extends DataService
     {
         public function countries()
         {
             return Cache::remember('custom_countries', now()->addDays(7), function () {
                 return Http::get('https://api.example.com/countries')->json();
             });
         }
     }
     

   • Bind the service in AppServiceProvider:

     $this->app->singleton(DataService::class, CustomDataService::class);
     

2. Adding New Data Types:

   • Publish the data files:

     php artisan vendor:publish --tag="moox-data-data"
     

   • Add your JSON data to database/data/ and update the DataService to parse it.

3. Custom Panel Views:

   • Override the panel views by publishing them:

     php artisan vendor:publish --tag="moox-data-views"
     

   • Modify resources/views/vendor/moox-data/panel.blade.php.