Suzie Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baskooijmaninc/suzie
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="BaskooijmanInc\Suzie\SuzieServiceProvider" --tag="suzie-config"
   

2. Basic Usage Import the Suzie facade or class:

   use BaskooijmanInc\Suzie\Facades\Suzie;
   
   // Example: Generate a "friendly" name from an input
   $friendlyName = Suzie::generate('JohnDoe123');
   echo $friendlyName; // Output: "John Doe"
   

3. First Use Case

   • User Display Names: Convert raw usernames (e.g., jane.doe_42) into readable formats (e.g., "Jane Doe").
   • API Responses: Sanitize or format data before returning to clients.

Implementation Patterns

Common Workflows

1. String Transformation Use Suzie::generate() to convert strings into human-readable formats:

   Suzie::generate('user_123_email@example.com')
   // Output: "User Email"
   

2. Custom Rules Extend default behavior via config or service provider:

   // config/suzie.php
   'rules' => [
       'separator' => '_',
       'replace' => [
           '123' => 'Number',
           'admin' => 'Administrator',
       ],
   ],
   

3. Middleware Integration Auto-format usernames in middleware:

   public function handle($request, Closure $next) {
       $request->merge(['formatted_name' => Suzie::generate($request->name)]);
       return $next($request);
   }
   

4. Model Observers Apply transformations on model events (e.g., retrieved):

   public function retrieved(Post $post) {
       $post->setAttribute('display_name', Suzie::generate($post->slug));
   }
   

Integration Tips

• Laravel Nova: Use in custom fields to display formatted data.
• API Resources: Transform attributes in toArray():

  public function toArray($request) {
      return [
          'name' => Suzie::generate($this->username),
      ];
  }
  

• Validation: Combine with Laravel’s validation for user input:

  $validated = $request->validate([
      'username' => ['required', 'string', Rule::unique('users')->ignore($user)],
  ]);
  $user->name = Suzie::generate($validated['username']);
  

Gotchas and Tips

Pitfalls

1. Overwriting Config If publishing the config, ensure you merge custom rules instead of replacing:

   // config/suzie.php
   return array_merge(require __DIR__.'/suzie.php', [
       'custom_rules' => [...],
   ]);
   

2. Performance Avoid calling Suzie::generate() in tight loops (e.g., bulk operations). Cache results:

   $cacheKey = "suzie_{$input}";
   $formatted = Cache::remember($cacheKey, now()->addHours(1), fn() => Suzie::generate($input));
   

3. Edge Cases

   • Empty Inputs: Handle null or empty strings:

     Suzie::generate($input ?? 'default_name');
     

   • Unicode/Non-ASCII: Test with names like José_Ramírez to ensure proper handling.

Debugging

• Log Rules: Temporarily log applied rules to debug transformations:

  Suzie::setCallback(function ($input, $output) {
      \Log::debug("Input: {$input} → Output: {$output}");
  });
  

Extension Points

1. Custom Generators Register new generators in the service provider:

   Suzie::extend('custom', function ($input) {
       return strtoupper($input);
   });
   

   Usage:

   Suzie::generate('test', 'custom'); // Output: "TEST"
   

2. Hooks Use events (if supported) to intercept transformations:

   event(new \BaskooijmanInc\Suzie\Events\Generating($input));
   

3. Testing Mock the facade in tests:

   $this->mock(Suzie::class)->shouldReceive('generate')->andReturn('Mocked Name');