Php Humanizer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coduo/php-humanizer
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Humanize a database column name in a Laravel view:

   use Coduo\PHPHumanizer\StringHumanizer;
   
   $humanized = StringHumanizer::humanize('user_id'); // "User id"
   return view('profile', ['fieldName' => $humanized]);
   

3. Key Classes to Know:

   • StringHumanizer (for text transformations)
   • NumberHumanizer (for numeric formatting)
   • DateTimeHumanizer (for time differences)
   • CollectionHumanizer (for list formatting)

Implementation Patterns

1. String Humanization in Eloquent Models

Pattern: Automatically humanize database column names for API responses or admin panels.

use Coduo\PHPHumanizer\StringHumanizer;

class User extends Model
{
    protected $hidden = ['password'];

    public function getHumanizedAttributes(array $attributes)
    {
        return collect($attributes)
            ->mapWithKeys(fn ($value, $key) => [
                StringHumanizer::humanize($key) => $value
            ]);
    }
}

Usage:

$user = User::find(1);
return response()->json($user->getHumanizedAttributes($user->toArray()));

2. File Size Formatting in Storage Responses

Pattern: Convert bytes to human-readable sizes (e.g., for file uploads).

use Coduo\PHPHumanizer\NumberHumanizer;

public function showFileSize(int $bytes)
{
    return NumberHumanizer::binarySuffix($bytes); // "1.2 MB"
}

Integration with Laravel:

use Illuminate\Support\Facades\Response;

return Response::json([
    'size' => NumberHumanizer::binarySuffix($file->size()),
    'name' => $file->name
]);

3. Time-Ago in Notifications

Pattern: Display relative time (e.g., "2 hours ago") in notifications.

use Coduo\PHPHumanizer\DateTimeHumanizer;

public function toArray($notifiable)
{
    return [
        'message' => "Post updated " . DateTimeHumanizer::difference(
            now(),
            $this->created_at
        ),
    ];
}

4. Collection Formatting for Lists

Pattern: Format lists of items (e.g., tags, authors) with Oxford commas.

use Coduo\PHPHumanizer\CollectionHumanizer;

$authors = ['J.K. Rowling', 'George R.R. Martin', 'Tolkien'];
$formatted = CollectionHumanizer::oxford($authors);
// "J.K. Rowling, George R.R. Martin, and 1 other"

Use Case: Admin panel filters or user profiles.

return view('profile', [
    'tags' => CollectionHumanizer::oxford($user->tags->pluck('name')->toArray())
]);

5. Customizing Humanizer for Multilingual Apps

Pattern: Override translations for locale-specific formatting.

// config/humanizer.php (if using a config package wrapper)
'humanizer' => [
    'locale' => app()->getLocale(),
    'translations' => [
        'difference' => [
            'pl' => [
                'seconds' => 'sekund',
                'minute'  => 'minut',
                // ... custom translations
            ],
        ],
    ],
],

Dynamic Locale Switching:

use Coduo\PHPHumanizer\DateTimeHumanizer;

$locale = app()->getLocale();
$difference = DateTimeHumanizer::difference(
    now(),
    $event->created_at,
    $locale
);

6. HTML Truncation in Blogs

Pattern: Safely truncate HTML content (e.g., blog excerpts).

use Coduo\PHPHumanizer\StringHumanizer;

$excerpt = StringHumanizer::truncateHtml(
    $post->content,
    50,
    '<strong><em><a>',
    '...'
);
// "<strong>Lorem ipsum...</strong>"

Gotchas and Tips

1. Locale-Specific Quirks

• Issue: binarySuffix() or metricSuffix() may use unexpected decimal separators (e.g., , vs .) in non-English locales. Fix: Explicitly pass the locale:

  NumberHumanizer::binarySuffix(1500, 'pl'); // "1,5 kB" (Polish)
  

• Tip: Cache locale-specific translations if performance is critical.

2. HTML Truncation Edge Cases

• Gotcha: truncateHtml() may break if the HTML tag is split mid-tag (e.g., truncating "<a href="). Fix: Whitelist allowed tags:

  StringHumanizer::truncateHtml($html, 100, '<a><strong>');
  

• Tip: Use strip_tags() as a fallback for untrusted HTML.

3. DateTime Precision Pitfalls

• Gotcha: preciseDifference() can produce overly verbose output for small time gaps. Fix: Combine with a threshold check:

  $diff = DateTimeHumanizer::difference($past, $now);
  $precise = strlen($diff) > 20
      ? DateTimeHumanizer::preciseDifference($past, $now)
      : $diff;
  

• Tip: Use DateTimeHumanizer::difference() for most cases; reserve preciseDifference() for detailed contexts.

4. String Humanization Rules

• Gotcha: humanize() converts underscores to spaces but may not handle camelCase optimally. Fix: Pre-process strings:

  StringHumanizer::humanize(str_replace(' ', '_', 'user first name'));
  // "User first name" (instead of "User_First_Name")
  

• Tip: For camelCase, use a regex:

  StringHumanizer::humanize(preg_replace('/([a-z])([A-Z])/', '$1 $2', 'userFirstName'));
  

5. Performance Considerations

• Gotcha: Heavy use of oxford() or preciseDifference() in loops can slow down responses. Fix: Cache results or limit precision:

  // Cache the formatted collection
  $cachedAuthors = Cache::remember("authors.{$user->id}", now()->addHours(1), function () use ($user) {
      return CollectionHumanizer::oxford($user->authors->pluck('name')->toArray());
  });
  

• Tip: Benchmark critical paths; avoid humanizing in model accessors if not needed.

6. Extension Points

• Custom Humanizers: Extend the package by creating a wrapper class:

  class AppHumanizer extends StringHumanizer
  {
      public static function humanizeWithTitle(string $text): string
      {
          return ucfirst(parent::humanize($text));
      }
  }
  

• Override Translations: Publish and modify the package’s translation files:

  php artisan vendor:publish --tag=humanizer-translations
  

  Then edit resources/lang/{locale}/humanizer.php.

7. Debugging Tips

• Unexpected Output: Check for locale mismatches or unhandled edge cases (e.g., empty strings in oxford()). Debug:

  dd(
      StringHumanizer::humanize(''),
      NumberHumanizer::binarySuffix(0),
      CollectionHumanizer::oxford([])
  );
  

• HTML Truncation Issues: Inspect the output with htmlspecialchars() to verify tag integrity:

  dd(htmlspecialchars(StringHumanizer::truncateHtml($html, 50)));
  

8. Laravel-Specific Integrations

• Service Provider Binding:

  public function register()
  {
      $this->app->singleton('humanizer', function () {
          return new AppHumanizer(); // Your extended class
      });
  }
  

• Form Request Validation:

  use Coduo\PHPHumanizer\StringHumanizer;
  
  public function rules()
  {
      return [
          'file_name' => [
              'required',
              function ($attribute, $value, $fail) {
                  if (strlen(StringHumanizer::humanize($value)) > 50) {
                      $fail('The ' . StringHumanizer::humanize($attribute) . ' may not be greater than 50 characters.');
                  }
              },
          ],
      ];
  }