Philarmony Utils Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require deozza/philarmony-utils
   

   Add the service provider to config/app.php:

   Deozza\PhilarmonyUtils\PhilarmonyUtilsServiceProvider::class,
   

2. First Use Case: String Manipulation The package provides utility methods for string manipulation, often used in validation or formatting.

   use Deozza\PhilarmonyUtils\StringUtils;
   
   $formatted = StringUtils::slugify('Hello World!'); // Returns 'hello-world'
   

3. Where to Look First

   • Facade: PhilarmonyUtils::slugify(), PhilarmonyUtils::camelCase(), etc.
   • Source: src/StringUtils.php for core logic.
   • Tests: tests/Unit/StringUtilsTest.php for usage examples.

Implementation Patterns

Common Workflows

1. String Transformation Use StringUtils for consistent formatting across the app (e.g., slugs, camelCase, snake_case).

   // In a controller or service
   $title = "User Profile Settings";
   $slug = StringUtils::slugify($title); // 'user-profile-settings'
   

2. Validation Helpers Combine with Laravel’s validation for reusable rules:

   use Deozza\PhilarmonyUtils\ValidationUtils;
   
   $validator = Validator::make($request->all(), [
       'username' => ['required', ValidationUtils::isAlphanumericWithUnderscores()]
   ]);
   

3. Integration with Blade Create a custom Blade directive for global string transformations:

   // In AppServiceProvider@boot()
   Blade::directive('slugify', function ($expression) {
       return "<?php echo Deozza\\PhilarmonyUtils\\StringUtils::slugify({$expression}); ?>";
   });
   

   Usage in Blade:

   <h1>{{ slugify('My Post Title') }}</h1> <!-- Renders as 'my-post-title' -->
   

4. API Response Formatting Normalize responses with ArrayUtils:

   use Deozza\PhilarmonyUtils\ArrayUtils;
   
   $response = [
       'data' => $user->toArray(),
       'meta' => ['count' => 1]
   ];
   return response()->json(ArrayUtils::normalizeKeys($response, 'snake_case'));
   

Best Practices

• Consistency: Use the same utility methods across controllers/services to avoid drift.
• Testing: Mock PhilarmonyUtils in unit tests to isolate logic:

  $this->partialMock(PhilarmonyUtils::class, ['slugify'])
       ->shouldReceive('slugify')
       ->once()
       ->andReturn('mocked-slug');
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts The package uses Deozza\PhilarmonyUtils—ensure no naming collisions with other Philarmony* packages.

2. Performance with Large Strings Methods like slugify() use regex. For bulk operations (e.g., 1000+ strings), cache results or batch process:

   $slugs = collect($titles)->map(fn($title) => cache()->remember(
       "slug_{$title}",
       now()->addHours(1),
       fn() => StringUtils::slugify($title)
   ));
   

3. Locale-Specific Transformations slugify() defaults to ASCII. For non-English apps, extend the class:

   class CustomStringUtils extends StringUtils {
       public static function slugify($string, $locale = 'en') {
           // Add locale-specific rules (e.g., handle 'ñ' in Spanish)
       }
   }
   

Debugging

• Unexpected Output: Check if input strings contain hidden characters (e.g., \x00). Use trim() or mb_convert_encoding() pre-processing.
• Validation Rules: If ValidationUtils rules fail silently, enable Laravel’s validation debugging:

  $validator->setAttributeNames(['username' => 'user name']);
  

Extension Points

1. Custom Utilities Extend the base classes (e.g., StringUtils) and bind them in the service provider:

   $this->app->singleton('custom.string.utils', function () {
       return new \App\Utils\CustomStringUtils();
   });
   

2. Configuration The package lacks a config file, but you can override defaults via facades:

   // Set global slug separator
   config(['philarmony-utils.defaults.slug_separator' => '-']);
   PhilarmonyUtils::setSlugSeparator('-');
   

3. Event Listeners Hook into string transformations via events (if the package supports them). Example for future-proofing:

   event(new StringTransformed($original, $transformed));