Laravel Dictionary Module Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require zxf5115/laravel-dictionary-module
   

   Publish the package config and migrations:

   php artisan vendor:publish --provider="Zxf5115\DictionaryModule\DictionaryServiceProvider" --tag=config
   php artisan vendor:publish --provider="Zxf5115\DictionaryModule\DictionaryServiceProvider" --tag=migrations
   php artisan migrate
   

2. First Use Case Define a dictionary via the dictionary Artisan command:

   php artisan dictionary:create --name="user_roles" --description="User role definitions"
   

   Add entries via the dictionary:entry command:

   php artisan dictionary:entry --name="user_roles" --key="admin" --value="Administrator"
   

3. Accessing Data Retrieve dictionary entries in code:

   $adminRole = \Zxf5115\DictionaryModule\Facades\Dictionary::get('user_roles', 'admin');
   // Returns "Administrator"
   

Implementation Patterns

Core Workflows

1. Dictionary Management

   • CRUD via Artisan:

     # Create/Update entries
     php artisan dictionary:entry --name="user_roles" --key="guest" --value="Guest User"
     
     # Delete entries
     php artisan dictionary:delete-entry --name="user_roles" --key="guest"
     

   • Bulk Operations: Use the dictionary:import command to load entries from a CSV/JSON file.

2. Integration with Eloquent Attach dictionaries to models via traits:

   use Zxf5115\DictionaryModule\Traits\HasDictionary;
   
   class User extends Model {
       use HasDictionary;
       protected $dictionaryName = 'user_roles';
   }
   

   Access dictionary values directly:

   $user->getDictionaryValue('admin'); // Returns "Administrator"
   

3. Localization Support Define dictionaries with language keys:

   php artisan dictionary:entry --name="lang" --key="welcome" --value="Welcome" --locale="en"
   

   Retrieve localized values:

   $welcome = \Zxf5115\DictionaryModule\Facades\Dictionary::get('lang', 'welcome', 'en');
   

4. Caching Enable caching in config/dictionary.php:

   'cache' => true,
   

   Clear cache manually:

   php artisan dictionary:clear-cache
   

Gotchas and Tips

Common Pitfalls

1. Case Sensitivity Dictionary keys are case-sensitive by default. Use strtolower() if case-insensitive behavior is needed:

   $value = \Zxf5115\DictionaryModule\Facades\Dictionary::get('dict_name', strtolower($key));
   

2. Migration Conflicts If migrations fail due to duplicate columns, manually check the dictionary_entries table schema. The package expects:

   -- Ensure these columns exist
   ALTER TABLE dictionary_entries ADD COLUMN IF NOT EXISTS `locale` VARCHAR(10) NULL;
   

3. Facade vs. Direct Service Prefer the facade for simplicity, but use the service container for dependency injection:

   // Bad: Tight coupling
   $value = \Zxf5115\DictionaryModule\Facades\Dictionary::get(...);
   
   // Good: Injected via constructor
   public function __construct(private DictionaryService $dictionary) {}
   

Debugging Tips

1. Log Missing Entries Enable debug mode in config/dictionary.php:

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

   Logs missing keys to storage/logs/laravel.log.

2. Validate Entries Use the validate-entry command to check for malformed data:

   php artisan dictionary:validate-entry --name="user_roles" --key="invalid_key"
   

3. Override Default Behavior Extend the DictionaryService class to customize logic:

   namespace App\Services;
   
   use Zxf5115\DictionaryModule\Services\DictionaryService as BaseService;
   
   class CustomDictionaryService extends BaseService {
       public function get($name, $key, $locale = null) {
           // Custom logic here
           return parent::get($name, $key, $locale);
       }
   }
   

   Bind the service in AppServiceProvider:

   $this->app->bind(
       \Zxf5115\DictionaryModule\Contracts\DictionaryService::class,
       App\Services\CustomDictionaryService::class
   );
   

Performance Quirks

1. Batch Fetching Fetch all entries for a dictionary at once to avoid N+1 queries:

   $entries = \Zxf5115\DictionaryModule\Facades\Dictionary::getAll('user_roles');
   

2. Cache Invalidation Manually invalidate cache after bulk operations:

   \Zxf5115\DictionaryModule\Facades\Dictionary::clearCache('user_roles');
   

3. Locale Fallback Configure fallback locales in config/dictionary.php:

   'fallback_locales' => ['en', 'zh'],
   

   The package will automatically fall back to the first available locale.