Getting Started

Minimal Steps

Installation Add the package via Composer:
```
composer require brandonwamboldt/utilphp
```
Register the facade (if using) in config/app.php under aliases:
```
'Util' => BrandonWamboldt\UtilPHP\Facades\Util::class,
```

First Use Case Import and use a utility function directly:

use BrandonWamboldt\UtilPHP\Util;

// Example: Generate a random string
$randomString = Util::randomString(10);

Or via facade:

$randomString = \Util::randomString(10);

Where to Look First
- Documentation: Check the GitHub README for a list of available functions.
- Source Code: Browse the src/Util directory for direct usage examples.
- Tests: Review the tests folder for practical use cases.

Implementation Patterns

Usage Patterns

Direct Function Calls Use static methods for lightweight utilities:

// String manipulation
$slug = Util::slugify('Hello World!');

// Array operations
$flattened = Util::flatten([1, [2, 3], 4]);

// Date handling
$formattedDate = Util::formatDate('2023-10-01', 'Y-m-d H:i:s');

Facade Integration Replace repetitive use statements with a facade for cleaner code:

// Before
use BrandonWamboldt\UtilPHP\Util;
$result = Util::camelCase('hello_world');

// After
$result = \Util::camelCase('hello_world');

Laravel Service Provider Integration Bind utilities to the container for dependency injection:

// In AppServiceProvider
public function register()
{
    $this->app->singleton('util', function () {
        return new \BrandonWamboldt\UtilPHP\Util();
    });
}

// Usage in controllers
public function __construct(private Util $util) {}

Customizing Defaults Extend or override default behaviors via configuration (if supported) or wrapper classes:

class CustomUtil extends \BrandonWamboldt\UtilPHP\Util
{
    public static function customSlugify($string)
    {
        return parent::slugify($string) . '-custom';
    }
}

Middleware for Global Utilities Attach utilities to middleware for request-wide access:

public function handle($request, Closure $next)
{
    $request->merge(['slug' => \Util::slugify($request->input('title'))]);
    return $next($request);
}

Workflows

Data Transformation Chain utilities for complex transformations:

$cleanedData = \Util::trim(\Util::slugify(\Util::lowercase($userInput)));

Validation Helpers Use utilities in Form Requests or custom validation rules:

public function rules()
{
    return [
        'email' => ['required', 'email', function ($attribute, $value, $fail) {
            if (!\Util::isValidEmail($value)) {
                $fail('Invalid email format.');
            }
        }]
    ];
}

Testing Utilities Leverage utilities in PHPUnit tests for consistent test data:

public function testUserCreation()
{
    $testUser = [
        'name' => \Util::randomString(10),
        'email' => \Util::randomEmail(),
    ];
    $this->post('/users', $testUser)->assertCreated();
}

API Response Formatting Standardize API responses using utilities:

return response()->json([
    'success' => true,
    'data' => \Util::arrayToObject($data),
    'timestamp' => \Util::formatDate(now(), 'Y-m-d H:i:s'),
]);

Gotchas and Tips

Pitfalls

Namespace Conflicts
- Issue: Some utility functions (e.g., array_* or str_*) may conflict with PHP built-ins.
- Fix: Use fully qualified namespaces or aliases:
```
\BrandonWamboldt\UtilPHP\Util::arrayMerge(...);
```
Facade Not Registered
- Issue: Forgetting to register the facade in config/app.php will cause Class 'Util' not found errors.
- Fix: Verify the alias exists:
```
'aliases' => [
    'Util' => BrandonWamboldt\UtilPHP\Facades\Util::class,
],
```
Static Method Limitations
- Issue: Static methods cannot be mocked easily in unit tests.
- Fix: Use dependency injection via the container or extend the class for testability:
```
$mockUtil = $this->createMock(\BrandonWamboldt\UtilPHP\Util::class);
```
Undocumented Changes
- Issue: The package lacks extensive documentation for edge cases.
- Fix: Check the GitHub issues or source code for undocumented behaviors.
Performance Overhead
- Issue: Some utilities (e.g., recursive functions) may impact performance for large datasets.
- Fix: Profile with Xdebug or tideways/xhprof and optimize critical paths.

Debugging

Enable Debugging Use dd() or dump() to inspect utility outputs:

dump(\Util::parseJson('{"key":"value"}')); // Debug JSON parsing

Check Return Types Some utilities return mixed types (e.g., null on failure). Always validate:

$result = \Util::parseJson($input);
if ($result === null) {
    abort(400, 'Invalid JSON');
}

Locale-Specific Functions
- Issue: Functions like formatDate or numberFormat may behave unexpectedly in non-English locales.
- Fix: Set the locale explicitly:
```
\Util::setLocale('en_US');
```

Tips

Extend the Package Create a custom utility class to override or extend functionality:

namespace App\Utilities;

use BrandonWamboldt\UtilPHP\Util as BaseUtil;

class AppUtil extends BaseUtil
{
    public static function appSlugify($string)
    {
        return parent::slugify($string) . '-app';
    }
}

Use in Blade Templates Register utilities globally for Blade access:

// In AppServiceProvider
Blade::if('util', function () {
    return new \BrandonWamboldt\UtilPHP\Facades\Util();
});

Then use in views:

{{ \Util::uppercase('hello') }}

Leverage for CLI Artisan Commands Use utilities in console commands for consistent output:

protected function handle()
{
    $this->info(\Util::formatDate(now(), 'Y-m-d H:i:s'));
}

Custom Configuration If the package supports config files (e.g., config/util.php), override defaults:

// In config/util.php
return [
    'default_locale' => 'en_US',
    'random_string_chars' => 'abcdefghijklmnopqrstuvwxyz0123456789',
];

Contribute Back
- Opportunity: The package has low stars and dependents, indicating room for growth.
- Action: Fork the repo, add missing utilities, and submit PRs. Example:
```
// Add a new utility in src/Util.php
public static function snakeCase($string)
{
    return strtolower(preg_replace('/[A-Z]/', '_$0', $string));
}
```

Utilphp Laravel Package