Bdf Util Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require b2pweb/bdf-util
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       B2PWeb\BDFUtil\BDFUtilServiceProvider::class,
   ],
   

2. First Use Case: Basic Helper Functions The package provides utility functions for common tasks like:

   • String manipulation (e.g., BDFUtil::slugify('Hello World') → hello-world).
   • Array operations (e.g., BDFUtil::flatten([1, [2, 3]]) → [1, 2, 3]).
   • Date/time handling (e.g., BDFUtil::formatDate('2023-01-01', 'd/m/Y')).
   • File/URL helpers (e.g., BDFUtil::getFileExtension('image.png')).

   Example:

   use B2PWeb\BDFUtil\Facades\BDFUtil;
   
   $slug = B2PUtil::slugify('My Awesome Post');
   // Returns: 'my-awesome-post'
   

3. Where to Look First

   • Facade: app/BDFUtil.php (if published) or vendor/b2pweb/bdf-util/src/Facades/BDFUtil.php.
   • Core methods: Check src/Helpers/BDFUtil.php for all available functions.
   • Documentation: If available, review the README.md for use cases. Otherwise, inspect the Helpers class directly.

Implementation Patterns

Common Workflows

1. String and Text Processing

• Slugification: Convert titles/headlines to SEO-friendly URLs.

  $title = "Laravel 10: New Features & Best Practices";
  $slug = BDFUtil::slugify($title, '-'); // 'laravel-10-new-features-best-practices'
  

• Truncation: Limit text length with ellipsis.

  $truncated = BDFUtil::truncate('Long text here...', 10); // 'Long text...'
  

• Template Replacement: Dynamic string templating.

  $template = "Hello {name}, welcome to {site}!";
  $result = BDFUtil::replaceTemplate($template, ['name' => 'John', 'site' => 'Laravel']);
  // 'Hello John, welcome to Laravel!'
  

2. Array Manipulation

• Flattening Nested Arrays:

  $nested = [1, [2, [3, 4]]];
  $flat = BDFUtil::flatten($nested); // [1, 2, 3, 4]
  

• Grouping by Key:

  $users = [
      ['name' => 'John', 'role' => 'admin'],
      ['name' => 'Jane', 'role' => 'user'],
  ];
  $grouped = BDFUtil::groupBy($users, 'role');
  // ['admin' => [...], 'user' => [...]]
  

• Merging with Custom Logic:

  $array1 = ['a' => 1, 'b' => 2];
  $array2 = ['b' => 3, 'c' => 4];
  $merged = BDFUtil::mergeArrays($array1, $array2, function ($val1, $val2) {
      return $val1 + $val2;
  });
  // ['a' => 1, 'b' => 5, 'c' => 4]
  

3. Date/Time Utilities

• Time Ago:

  $ago = BDFUtil::timeAgo('2023-01-01'); // '2 years ago'
  

• Date Formatting:

  $formatted = BDFUtil::formatDate('2023-12-25', 'Y-m-d H:i:s'); // '2023-12-25 00:00:00'
  

• Carbon Integration: If the package uses Carbon, leverage its methods alongside BDFUtil:

  $carbon = BDFUtil::parseDate('2023-01-01');
  $carbon->addDays(5);
  

4. File and URL Helpers

• Extract File Info:

  $extension = BDFUtil::getFileExtension('document.pdf'); // 'pdf'
  $mime = BDFUtil::getMimeType('document.pdf'); // 'application/pdf'
  

• URL Manipulation:

  $baseUrl = 'https://example.com';
  $fullUrl = BDFUtil::makeUrl($baseUrl, '/posts/1'); // 'https://example.com/posts/1'
  

5. Integration with Laravel Components

• Form Requests: Use slugify for route parameters.

  // In a Form Request
  public function rules()
  {
      return [
          'title' => 'required|string',
          'slug' => 'required|unique:posts|slug:title', // Custom rule using BDFUtil
      ];
  }
  

• Blade Directives: Create custom Blade helpers.

  // In a service provider
  Blade::directive('slug', function ($expression) {
      return "<?php echo BDFUtil::slugify({$expression}); ?>";
  });
  

  Usage in Blade:

  <h1>{{ slug($post->title) }}</h1>
  

6. Customizing Behavior

• Override Defaults: Publish the config (if available) and customize:

  php artisan vendor:publish --provider="B2PWeb\BDFUtil\BDFUtilServiceProvider" --tag="config"
  

  Example config (config/bdf-util.php):

  'slug_separator' => '_', // Default is '-'
  'default_locale' => 'en_US',
  

Gotchas and Tips

Pitfalls and Debugging

1. Facade vs. Helper Class

   • The package may expose both a facade (BDFUtil) and a static helper class (\B2PWeb\BDFUtil\Helpers\BDFUtil).
   • Gotcha: If autoloading fails, ensure the facade is properly registered in config/app.php.
   • Tip: Use the facade for consistency in Blade/views and the helper class in non-facade contexts (e.g., service containers).

2. Locale-Sensitive Functions

   • Functions like formatDate or timeAgo may rely on the app’s locale.
   • Gotcha: Unexpected output if the locale isn’t set (e.g., config/app.php).
   • Tip: Explicitly pass a locale:

     BDFUtil::formatDate('2023-12-25', 'd/m/Y', 'fr_FR'); // '25/12/2023'
     

3. Array Manipulation Side Effects

   • Functions like flatten or groupBy may return new arrays without modifying the original.
   • Gotcha: Assuming in-place modification (e.g., $array = BDFUtil::flatten($array) won’t alter $array unless documented).
   • Tip: Use BDFUtil::flatten($array, true) if a "mutate" option exists (check docs).

4. File/URL Helper Limitations

   • getMimeType may not support all file types out of the box.
   • Gotcha: Returns null or a generic type for unsupported files.
   • Tip: Extend the package or use a dedicated library like mime/mime-types for robust MIME detection.

5. Performance with Large Arrays

   • Functions like flatten or groupBy may be resource-intensive for large datasets.
   • Gotcha: Timeouts or high memory usage in loops.
   • Tip: Process data in chunks or use Laravel collections for lazy evaluation:

     $flat = collect($nestedArray)->flatten()->toArray();
     

6. Missing Documentation

   • Gotcha: Undocumented methods or edge cases (e.g., slugify handling special characters).
   • Tip: Inspect the source (src/Helpers/BDFUtil.php) for undocumented features or edge cases. Example:

     BDFUtil::slugify('Café au Lait'); // 'caf-au-lait' (handles accents)
     

Extension Points

1. Add Custom Helpers
   • Extend the BDFUtil class or create a decorator:

     class CustomBDFUtil extends \B2PWeb\BDFUtil\Helpers\