Laraviz Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require vizrex/laraviz
   

   Add the package to providers in config/app.php if not auto-discovered.

2. First Use Case: Extending a Command Create a new Artisan command extending Vizrex\Laraviz\Console\BaseCommand:

   use Vizrex\Laraviz\Console\BaseCommand;
   
   class MyCommand extends BaseCommand
   {
       protected $signature = 'my:command';
       protected $description = 'My custom command';
   
       public function handle()
       {
           $this->debug('Debug message (visible only with -vvvv)');
           $this->info($this->str('key.in.translation'));
       }
   
       protected function setNamespace()
       {
           $this->namespace = 'commands';
       }
   
       protected function setDefaultTranslationFile()
       {
           $this->defaultTranslationFile = 'my-command';
       }
   }
   

3. Where to Look First

   • Review BaseCommand in vendor/vizrex/laraviz/src/Console/BaseCommand.php for core methods.
   • Check BaseServiceProvider for getNamespace() implementation patterns.
   • Explore resources/lang/{locale}/my-command.php for translation files.

Implementation Patterns

Core Workflows

1. Command Development

   • Extend BaseCommand for all CLI tools.
   • Implement setNamespace() to align with your package’s translation namespace (e.g., 'vizrex/my-package').
   • Use setDefaultTranslationFile() to define the base translation file (e.g., 'my-package').
   • Leverage debug() for verbose logging (visible only with -vvvv).
   • Use str() for localized strings (auto-falls back to __() or trans()).

2. Translation Management

   • Store translations in resources/lang/{locale}/{translation-file}.php.
   • Example structure:

     resources/lang/en/my-command.php
     resources/lang/es/my-command.php
     

   • Access keys via $this->str('key.in.my-command').

3. Service Provider Integration

   • Extend BaseServiceProvider to centralize namespace logic:

     class MyServiceProvider extends BaseServiceProvider
     {
         public static function getNamespace(): string
         {
             return 'vizrex/my-package';
         }
     }
     

   • Pass the namespace to commands via setNamespace().

4. Verbose Debugging

   • Use debug() for conditional logging:

     $this->debug('Detailed debug info', ['var' => $variable]);
     

   • Run commands with -vvvv to see output.

Integration Tips

• For Packages: Bundle vizrex/laraviz as a dependency and enforce BaseCommand/BaseServiceProvider in your package’s docs.
• For Apps: Use the package to standardize CLI tools across projects (e.g., shared translation keys, verbose logging).
• Testing: Mock debug() output in tests by checking $command->output->verbose() or $command->output->wrapped().

Gotchas and Tips

Pitfalls

1. Namespace Mismatches

   • If setNamespace() and BaseServiceProvider::getNamespace() return mismatched values, translations will fail to load.
   • Fix: Ensure consistency between the two sources.

2. Translation File Not Found

   • If setDefaultTranslationFile() is missing or misconfigured, str() will throw an error.
   • Fix: Always implement setDefaultTranslationFile() and verify the file exists in resources/lang/.

3. Verbose Mode Ignored

   • debug() output won’t appear unless -vvvv is used.
   • Fix: Document this requirement in your command’s help text.

4. Static Method Dependencies

   • BaseServiceProvider::getNamespace() is static, so it cannot access instance properties.
   • Fix: Use dependency injection or a singleton pattern if dynamic namespace resolution is needed.

Debugging

• Check Output Levels:
  • -v: Normal output.
  • -vv: More verbose.
  • -vvv: Debug output.
  • -vvvv: debug() output.
• Inspect Translations:
  • Dump the loaded translations with:

    $this->debug('Loaded translations:', [
        'keys' => config('app.locale'),
        'files' => $this->defaultTranslationFile,
    ]);
    

• Verify Namespace:
  • Log the namespace in handle():

    $this->debug('Namespace:', [$this->namespace]);
    

Extension Points

1. Customize debug() Override the method to add timestamps or log levels:

   protected function debug($message, array $context = [])
   {
       if ($this->option('verbose')) {
           $this->line('<comment>[' . now()->format('H:i:s') . ']</comment> ' . $message);
       }
   }
   

2. Add Translation Fallbacks Extend str() to support fallback locales:

   protected function str($key, array $replace = [], $locale = null)
   {
       $locale = $locale ?: app()->getLocale();
       return trans("{$this->namespace}::{$this->defaultTranslationFile}.{$key}", $replace, $locale);
   }
   

3. Dynamic Translation Files Load translation files dynamically based on runtime conditions:

   protected function setDefaultTranslationFile()
   {
       $this->defaultTranslationFile = 'dynamic-' . request()->input('type');
   }
   

4. Integration with Laravel Mix Use debug() to log asset compilation steps:

   $this->debug('Compiling assets for environment: ' . config('app.env'));