Getting Started

Minimal Setup

Installation:
```
composer require dragon-code/support
```

Facade Registration: The package uses facades for all helpers. Register the facades in config/app.php under aliases:

'aliases' => [
    // ...
    'Arr' => DragonCode\Support\Facades\Arr::class,
    'Str' => DragonCode\Support\Facades\Str::class,
    'File' => DragonCode\Support\Facades\File::class,
    'Digit' => DragonCode\Support\Facades\Digit::class,
    // ... other facades as needed
],

First Use Case: Use Arr for array manipulation or Str for string operations in your Laravel controllers/services:
```
use Arr;
use Str;

$flattened = Arr::flattenKeys(['a' => ['b' => 1]]);
$slug = Str::slug('Hello World');
```

Key Entry Points

Facades: Arr, Str, File, Digit, Instance, etc.
Documentation: Check the GitHub repository for method signatures and examples.
Testing: Run php artisan vendor:publish --tag=support-config if configuration publishing is needed (though unlikely for this package).

Implementation Patterns

Common Workflows

1. Array Manipulation

Flattening Nested Arrays:

$array = ['a' => ['b' => 1, 'c' => 2]];
$flattened = Arr::flattenKeys($array);
// Result: ['a.b' => 1, 'a.c' => 2]

Invokable Collections:

$collection = Arr::of(['a', 'b', 'c'])->addUnique('d')->toArray();
// Result: ['a', 'b', 'c', 'd']

2. String Operations

Slug Generation:

$slug = Str::slug('Hello World', '-');
// Result: 'hello-world'

Regex Matching:

$matches = Str::matchAll('/\d+/', 'Order 123');
// Result: ['123']

3. Filesystem Tasks

Directory Operations:

File::directory('path/to/dir')->copy('path/to/new/dir');

File Content:

$content = File::load('path/to/file.txt');

4. Type Checking and Conversion

Instance Checks:

if (Instance::of($var, \DateTime::class)) {
    // Handle DateTime
}

Number Formatting:

$shortNumber = Digit::toShort(1000000, 'M');
// Result: '1M'

Integration Tips

Replace Native PHP/Collections: Use Arr or Str facades instead of raw PHP functions (e.g., array_merge, str_replace) for consistency and potential future extensions.
```
// Instead of:
$merged = array_merge($array1, $array2);

// Use:
$merged = Arr::merge($array1, $array2);
```

Leverage Invokable Helpers: Chain methods on Arr::of() or Str::of() for fluent syntax:

$result = Arr::of($data)
    ->filter(fn($value) => $value > 0)
    ->map(fn($value) => $value * 2)
    ->toArray();

Extend for Custom Logic: Add new methods to existing classes (e.g., Arr, Str) by:
- Extending the class in your project.
- Contributing back to the package (as per contribution guidelines).
Testing: Mock facades in tests using Laravel’s MockFacade or replace them with direct class calls for isolation:
```
$this->partialMock(Arr::class, ['flattenKeys']);
```
Configuration: Publish config (if available) with:
```
php artisan vendor:publish --tag=support-config
```
(Note: The package may not include config files; check the repo.)

Gotchas and Tips

Pitfalls

Facade Initialization:
- Facades must be registered in config/app.php before use. If you encounter Class not found errors, verify the alias is correctly added.
- Example error: Class 'Arr' not found → Ensure 'Arr' => DragonCode\Support\Facades\Arr::class is in aliases.
Method Signature Mismatches:
- Some methods (e.g., Arr::flattenKeys) may behave differently with mixed input types. Refer to the release notes for fixes (e.g., #295).
- Example:
```
Arr::flattenKeys(['a' => [1, 'b' => 2]]); // May throw errors; test edge cases.
```
PHP Version Compatibility:
- The package requires PHP 8.1+. Ensure your project meets this requirement (check release 6.13.0).
- Example error: PHP 8.0 not supported → Upgrade PHP or use an older package version.
Filesystem Permissions:
- Methods like File::load() or Directory::copy() may fail silently or throw exceptions if permissions are insufficient. Validate paths and permissions:
```
if (!is_readable('path/to/file')) {
    throw new \RuntimeException('File not readable');
}
```

Invokable Helper Quirks:

Methods like Arr::of()->toInstance() may return unexpected types. Test return values:

$instance = Arr::of(['key' => 'value'])->toInstance();
// Ensure $instance is the expected class (e.g., stdClass).

Debugging Tips

Log Facade Calls: Temporarily replace facades with direct class calls to debug:

// In tests or debug code:
$result = \DragonCode\Support\Arr::flattenKeys($data);

Check Release Notes:
- Recent fixes (e.g., #292) address edge cases like Uninitialized string offset. Review the changelog for relevant updates.
Enable Strict Typing: Use PHP’s declare(strict_types=1) to catch type-related issues early.
Test Edge Cases:
- Empty arrays, null values, or mixed types (e.g., ['a' => [1, 'b']]) may break methods. Write tests for these scenarios.

Extension Points

Add Custom Methods:

Extend a facade class (e.g., DragonCode\Support\Arr) in your project:

namespace App\Support;

use DragonCode\Support\Arr as BaseArr;

class Arr extends BaseArr {
    public static function customMethod(array $array) {
        return array_filter($array, fn($value) => $value > 100);
    }
}

Update the facade alias in config/app.php to point to your extended class.

Contribute to the Package:
- Follow the contribution guide to add methods or fix issues. Key steps:
  1. Add the method to the appropriate class (e.g., DragonCode\Support\Str).
  2. Update the facade’s docblock (e.g., DragonCode\Support\Facades\Str).
  3. Write tests in Tests/Unit/Str/<MethodName>Test.
  4. Submit a PR.

Override Default Behavior:

Bind the package’s classes to the container in AppServiceProvider:

$this->app->bind(
    \DragonCode\Support\Arr::class,
    fn($app) => new \App\Support\CustomArr()
);

Performance Considerations

Avoid Overhead in Loops:

Facade calls add slight overhead. For performance-critical loops, use direct class calls:

// Slow (facade):
foreach ($data as $item) {
    $processed = Arr::flattenKeys($item);
}

// Faster (direct):
foreach ($data as $item) {
    $processed = \DragonCode\Support\Arr::flattenKeys($item);
}

**Cache Complex Operations

Support Laravel Package