Getting Started

First Steps

Installation Add the package via Composer (updated for latest features):
```
composer require denisok94/helper:^0.8.7
```
No publisher or service provider is required—just autoload the classes.
Locate Core Classes The package provides utility classes in Denisok94\Helper\ namespace. Key classes include:
- StringHelper (string manipulation, now with deNormalize, truncatePro, and truncateGrapheme)
- ArrayHelper (array operations)
- FileHelper (file/directory handling)
- DateHelper (date/time utilities)

First Use Case Use the new StringHelper methods to handle advanced string normalization and truncation:

use Denisok94\Helper\StringHelper;

// Denormalize a string (reverse of normalizing)
$denormalized = StringHelper::deNormalize('hello-world'); // e.g., 'Hello World'

// Truncate with proper grapheme cluster support (handles emojis, ligatures)
$truncated = StringHelper::truncateGrapheme('Hello 🌍 world!', 10); // 'Hello 🌍...'

Implementation Patterns

Common Workflows

Enhanced String Manipulation Leverage the new StringHelper methods for edge cases:

// Denormalize for display purposes (e.g., converting slugs to readable text)
$title = StringHelper::deNormalize('user-profile-settings');

// Truncate with grapheme awareness (critical for multilingual apps)
$preview = StringHelper::truncateGrapheme($longText, 50);

// Truncate with ellipsis and custom separator (pro version)
$shortened = StringHelper::truncatePro($longText, 20, '...');

Array Operations Use ArrayHelper for complex array logic (unchanged):

// Group associative array by key
$grouped = ArrayHelper::groupBy($users, 'department');

File Handling Simplify file operations in Laravel’s filesystem (unchanged):

// Read file as chunks
$chunks = FileHelper::readFileInChunks('large-file.log', 1024);

Date/Time Utilities Extend Laravel’s Carbon with DateHelper (unchanged):
```
// Human-readable diff
$diff = DateHelper::timeAgoInWords(now());
```

Integration Tips

Service Container Binding Bind helpers to Laravel’s container for global access (unchanged):
```
$this->app->bind('helper.string', fn() => new StringHelper());
```

Facade Pattern Create a facade for cleaner syntax (optional, unchanged):

// app/Facades/HelperFacade.php
class HelperFacade extends Facade {
    protected static function getFacadeAccessor() { return 'helper.string'; }
}

Form Request Validation Use StringHelper in FormRequest rules (now with new methods):

public function rules() {
    return [
        'title' => [
            'required',
            Rule::function(fn($attr, $value) =>
                StringHelper::length($value) <= 100
            ),
            Rule::function(fn($attr, $value) =>
                StringHelper::truncateGrapheme($value, 50) === $value // Ensure no truncation needed
            ),
        ],
    ];
}

Gotchas and Tips

Pitfalls

Namespace Collisions The package lacks a unique namespace prefix (e.g., Helper vs. Laravel’s Helper). Avoid naming conflicts by:
- Using fully qualified class names:
```
\Denisok94\Helper\StringHelper::deNormalize(...);
```
Undocumented Methods New methods may have edge cases:
- deNormalize: Behavior with mixed-case input (e.g., 'Hello-World' → 'Hello World') may vary. Test thoroughly.
- truncateGrapheme: May not handle all Unicode edge cases (e.g., surrogate pairs). Validate with:
```
$text = "Hello \u{D83D}\u{DE00}"; // Emoji
$truncated = StringHelper::truncateGrapheme($text, 5);
// Expected: 'Hello' (not 'Hell...' if grapheme cluster not split correctly)
```
Performance Overhead Avoid heavy operations (e.g., FileHelper::readFileInChunks) in loops or critical paths. Profile with:
```
php artisan tinker
\Denisok94\Helper\Benchmark::time(fn() => StringHelper::truncateGrapheme($longText, 1000));
```
Session Fix Note The release notes mention a "fixs Session" (likely a typo for "fixes Session"). If you rely on session-related functionality in the package, verify behavior in:
- Session storage/retrieval.
- Session-based caching (if applicable).

Debugging Tips

Enable Error Reporting Add to config/app.php (unchanged):

'providers' => [
    // ... (no provider needed per package docs)
],

Log Helper Usage Wrap new StringHelper calls in a logger for auditing:

Log::debug('StringHelper::truncateGrapheme', [
    'input' => $longText,
    'output' => StringHelper::truncateGrapheme($longText, 50),
    'length' => mb_strlen($longText, '8bit'),
]);

Extension Points

Custom String Helpers Extend StringHelper to override new methods:

class CustomStringHelper extends StringHelper {
    public static function customDeNormalize($string) {
        return parent::deNormalize($string) . ' (custom)';
    }
}

Grapheme-Aware Truncation Override truncateGrapheme for custom logic:

class AppStringHelper extends StringHelper {
    public static function truncateGrapheme($string, $length, $suffix = '...') {
        $truncated = parent::truncateGrapheme($string, $length, $suffix);
        // Add app-specific logic (e.g., replace suffix for certain languages)
        return str_contains($string, '🌍') ? $truncated . ' [global]' : $truncated;
    }
}

Configuration If the package gains config support in future releases, publish assets:
```
php artisan vendor:publish --tag=helper-config --provider="Denisok94\Helper\HelperServiceProvider"
```
(Check if the package adds this in future versions.)

Testing Mock new methods in PHPUnit:

$this->partialMock(StringHelper::class, ['truncateGrapheme'])
     ->shouldReceive('truncateGrapheme')
     ->with($longText, 50)
     ->andReturn('mocked...');

Multilingual Support Use truncateGrapheme for:

Right-to-left (RTL) languages (e.g., Arabic, Hebrew).
Emoji/emoticon handling. Test with:

$rtlText = 'مرحبا بالعالم!';
$truncatedRTL = StringHelper::truncateGrapheme($rtlText, 5); // Should not split 'مرحبا'

Helper Laravel Package