Getting Started

Install via Composer:

composer require respect/stringifier

First Use Case: Replace ad-hoc string casting in Laravel logs or debugging:

use function Respect\Stringifier\stringify;

// Before: (string)$request->input('data')
// After:
Log::debug('Request data:', stringify($request->input('data')));

// For objects/arrays:
Log::debug('User:', stringify($user));

Key Starting Points:

Function API: Use stringify($value) for quick conversions.
Object API: Use HandlerStringifier for customization (e.g., HandlerStringifier::create()).

Laravel Integration: Override toString() in models or use a macro for Eloquent collections:

use Respect\Stringifier\stringify;

Collection::macro('toString', function () {
    return stringify($this->all());
});

Implementation Patterns

Core Workflows

Logging and Debugging:

// Monolog handler
$handler = new \Monolog\Handler\StreamHandler(storage_path('logs/debug.log'));
$handler->pushProcessor(function ($record) {
    $record['context']['data'] = stringify($record['context']['data'] ?? null);
    return $record;
});

// Artisan commands
$this->info('Processing: ' . stringify($this->argument('data')));

API Responses:

// Custom JSON response formatter
Response::macro('stringify', function ($data) {
    return response()->json(['data' => stringify($data)]);
});

// Usage:
return response()->stringify($complexObject);

Validation Error Messages:

// FormRequest validation
public function failedValidation(Validator $validator) {
    $errors = stringify($validator->errors()->toArray());
    return response()->json(['errors' => $errors], 422);
}

Caching Keys:

// Dynamic cache keys for complex objects
$cacheKey = 'user_' . stringify($user->id . $user->role);
Cache::put($cacheKey, $user);

Laravel-Specific Patterns

Eloquent Model Stringification:

// Override toString() in a model
public function toString(): string {
    return stringify([
        'id' => $this->id,
        'name' => $this->name,
        'created_at' => $this->created_at,
    ]);
}

Service Container Binding:

// Bind a custom stringifier for specific use cases
$app->bind('custom.stringifier', function () {
    $handler = HandlerStringifier::create();
    $handler->addStringifier(new class implements Handler {
        public function handle(mixed $raw, int $depth): ?string {
            if ($raw instanceof YourCustomClass) {
                return 'CustomClass{' . $raw->id . '}';
            }
            return null;
        }
    });
    return $handler;
});

Exception Handling:

// Custom exception formatter
App::error(function (Throwable $e, $request) {
    return response()->json([
        'error' => stringify($e),
        'trace' => stringify($e->getTrace()),
    ]);
});

Testing:

// Assert stringified output in tests
$this->assertEquals(
    'User{id:1,name:"John"}',
    stringify(new User(['id' => 1, 'name' => 'John']))
);

Gotchas and Tips

Pitfalls

Version 2.0 Security Risks:
- Problem: Exposes internal class/interface names in stringified output.
- Fix: Downgrade to v1.x or disable sensitive detection:
```
$stringifier = HandlerStringifier::create();
$stringifier->setOptions(['detect_classes' => false]);
```
Performance with Deep Objects:
- Problem: Recursive stringification of deeply nested objects may hit PHP’s recursion limit.
- Fix: Set a depth limit:
```
$stringifier = HandlerStringifier::create();
$stringifier->setMaxDepth(5); // Default is 10
```
Resource Leaks:
- Problem: Stringifying resources (e.g., tmpfile()) may not close them properly.
- Fix: Avoid stringifying resources directly; use get_resource_type() or custom handlers.
Closure/Callable Output:
- Problem: Closures may expose sensitive function names.
- Fix: Mask or disable callable detection:
```
$handler = CompositeHandler::create();
$handler->removeStringifier(CallableStringifier::class);
```
False Positives in is_callable:
- Problem: Arrays like ['foo', 'bar'] may be misinterpreted as callables.
- Fix: Use v1.x or whitelist safe arrays.

Debugging Tips

Inspect Handlers:
- List registered handlers to debug why a value isn’t stringified as expected:
```
$stringifier = HandlerStringifier::create();
print_r($stringifier->getHandlers());
```

Custom Fallback:

Replace DumpStringifier with a custom fallback for unsupported types:

$stringifier = new HandlerStringifier(
    CompositeHandler::create(),
    new class implements Stringify {
        public function stringify(mixed $raw, int $depth): string {
            return '[Unsupported: ' . gettype($raw) . ']';
        }
    }
);

Logging Stringifier Output:

Log the stringification process to debug edge cases:

$stringifier = HandlerStringifier::create();
$stringifier->addStringifier(new class implements Handler {
    public function handle(mixed $raw, int $depth): ?string {
        Log::debug('Stringifying:', ['value' => $raw, 'depth' => $depth]);
        return null; // Let other handlers process it
    }
});

Extension Points

Custom Handlers:

Create a handler for domain-specific types (e.g., Carbon\Carbon):

$handler = new class implements Handler {
    public function handle(mixed $raw, int $depth): ?string {
        if ($raw instanceof Carbon\Carbon) {
            return $raw->format('Y-m-d H:i:s');
        }
        return null;
    }
};
$stringifier->addStringifier($handler);

Pre/Post Processing:

Wrap the stringifier to add metadata or sanitize output:

$stringifier = new class($delegate) implements Stringify {
    public function __construct(private Stringify $delegate) {}
    public function stringify(mixed $raw, int $depth): string {
        $result = $this->delegate->stringify($raw, $depth);
        return '[Sanitized] ' . str_replace(['{', '}'], '', $result);
    }
};

Conditional Stringification:

Skip stringification for specific types (e.g., sensitive data):

$handler = new class implements Handler {
    public function handle(mixed $raw, int $depth): ?string {
        if ($raw instanceof SensitiveData) {
            return '[REDACTED]';
        }
        return null;
    }
};

Laravel-Specific Quirks

Eloquent Relationships:
- Stringifying Eloquent models with lazy-loaded relationships may cause N+1 queries.
- Fix: Eager-load relationships first:
```
$user = User::with('posts')->find(1);
stringify($user); // Safe
```

Collection Macros:

If using Collection::macro('toString'), ensure it doesn’t conflict with existing macros:

if (!Collection::hasMacro('toString')) {
    Collection::macro('toString', function () {
        return stringify($this->all());
    });
}

Service Provider Boot:

public function boot() {
    $app->singleton('stringifier', function () {
        return HandlerStringifier::create();
    });
}

Testing:
- Mock the stringifier in tests to avoid real object instantiation:
```
$this->app->instance('stringifier', Mockery::mock(Stringify::class));
```

Stringifier Laravel Package