Getting Started

Minimal Steps

Installation
```
composer require wp-starter/support
```
Verify compatibility with Laravel’s PHP version (7.3+ or 8.0+) and dependencies like wp-starter/collections and nesbot/carbon.

First Use Case: Collections Macros The package likely extends Laravel’s collections with custom macros. Test this by adding a macro:

use Illuminate\Support\Collection;
use WpStarter\Support\Support;

Collection::macro('toSnake', function () {
    return $this->map(fn ($item) => Support::snake($item));
});

// Usage:
$snakeCollection = collect(['HelloWorld', 'FooBar'])->toSnake();

Where to Look First
- Source Code: Start with src/Support.php or src/CollectionMacros.php for core functionality.
- Tests: Check tests/ for usage examples (though minimal due to package age).
- Facade/Service Provider: Look for SupportServiceProvider.php to understand registration.

Initial Integration

'providers' => [
    WpStarter\Support\SupportServiceProvider::class,
],

Use the facade (if available) or class directly:

use WpStarter\Support\Facades\Support;

// Example: Format a date with Carbon
$formattedDate = Support::now()->format('Y-m-d');

Implementation Patterns

Core Usage Patterns

1. Macroable Collections

Pattern: Extend Laravel collections with domain-specific macros for support workflows.

// Define a macro for ticket categorization
Collection::macro('categorizeTickets', function () {
    return $this->groupBy(fn ($ticket) => $ticket['priority']);
});

// Usage in a controller
$tickets = Ticket::all()->categorizeTickets();

Integration Tip: Use this to encapsulate repetitive logic (e.g., ticket routing, user filtering).

2. Carbon Integration for Time-Based Workflows

Pattern: Leverage Carbon for support SLAs or deadlines.

use WpStarter\Support\Facades\Support;

$dueDate = Support::now()->addDays(3); // SLA deadline
$isOverdue = $dueDate->isPast();

Workflow: Attach this to Eloquent models (e.g., Ticket):

class Ticket extends Model {
    public function isOverdue() {
        return $this->due_date->isPast();
    }
}

3. String and Data Formatting

Pattern: Standardize string formatting (e.g., snake_case, human-readable labels).

// Convert to human-readable (e.g., "1 ticket" -> "1 Ticket")
$label = Support::humanize(1, 'ticket');

// Snake case conversion
$snake = Support::snake('HelloWorld');

Use Case: Apply to API responses or Blade templates for consistency.

4. Contract-Based Extensibility

Pattern: Use wp-starter/contracts to define interfaces for support services (e.g., TicketRepository).

namespace WpStarter\Support\Contracts;

interface TicketRepository {
    public function findByPriority(string $priority);
}

Integration Tip: Implement contracts in your app to decouple logic:

class EloquentTicketRepository implements TicketRepository {
    public function findByPriority(string $priority) {
        return Ticket::where('priority', $priority)->get();
    }
}

Workflows

Ticketing System

Define Macros:

Collection::macro('filterByStatus', function ($status) {
    return $this->where('status', $status);
});

Use in Controller:

$openTickets = Ticket::all()->filterByStatus('open');

Extend with Carbon:

$overdue = $openTickets->filter(fn ($ticket) => $ticket->due_date->isPast());

User Support Portal

Humanize Data:

$ticketCount = Support::humanize($count, 'ticket');

Localization (if supported):

$translated = Support::translate('support.label.ticket');

Automated Alerts

Schedule with Carbon:

$reminder = Support::now()->addHours(1);

Trigger via Laravel Scheduler:

$schedule->command('send-overdue-alerts')->hourlyAt($reminder->format('H:i'));

Gotchas and Tips

Pitfalls

WordPress Legacy Code
- Issue: The package may contain WordPress-specific logic (e.g., WP_ classes, hooks).
- Fix: Audit the codebase for non-Laravel dependencies. Replace with Laravel equivalents (e.g., WP_User_Query → User::query()).
Undocumented Macros
- Issue: Macros may not be documented, leading to unclear usage.
- Fix: Inspect the CollectionMacros class or tests to infer functionality. Add PHPDoc comments:
```
/**
 * @param Collection $collection
 * @return Collection
 */
Collection::macro('toSnake', function ($collection) { ... });
```
Carbon Version Conflicts
- Issue: The package may require a specific Carbon version, conflicting with Laravel’s.
- Fix: Pin Carbon in composer.json:
```
"nesbot/carbon": "^2.55"
```

No Laravel Service Provider

Issue: The package might not register itself automatically.

Fix: Manually register in AppServiceProvider:

public function register() {
    if (! app()->bound('support')) {
        $this->app->bind('support', function () {
            return new \WpStarter\Support\Support();
        });
    }
}

Lack of Testing

Issue: Minimal test coverage may lead to edge-case bugs.

Fix: Write integration tests for critical paths:

public function testTicketCategorization() {
    $tickets = collect([['priority' => 'high'], ['priority' => 'low']]);
    $categorized = $tickets->categorizeTickets();
    $this->assertArrayHasKey('high', $categorized);
}

Debugging Tips

Enable Debugging for Macros Add this to AppServiceProvider to log macro calls:

Collection::macro('debug', function () {
    \Log::debug('Collection macro called: ' . debug_backtrace()[1]['function']);
    return $this;
});

Check for WordPress Dependencies Run a grep to find non-Laravel classes:
```
grep -r "WP_" vendor/wp-starter/support
```

Override Problematic Methods If a method conflicts with Laravel’s, override it in a trait:

namespace App\Support;

use WpStarter\Support\Support as BaseSupport;

class Support extends BaseSupport {
    public static function snake($string) {
        return Str::snake($string); // Use Laravel's Str
    }
}

Extension Points

Add Custom Macros Extend collections globally or per-project:

// Global macro
Collection::macro('toTitleCase', function () {
    return $this->map(fn ($item) => ucwords(strtolower($item)));
});

// Project-specific macro (in a service provider)
Collection::macro('filterActive', function () {
    return $this->where('is_active', true);
});

Integrate with Eloquent Attach macros to model collections:

class Ticket extends Model {
    public function scopeOverdue($query) {
        return $query->where('due_date', '<', now());
    }
}
// Usage:
$overdue = Ticket::overdue()->get();

Localization Support If the package lacks Laravel’s trans() integration, create a wrapper:

Support::macro('translate', function ($key, $replace = []) {
    return trans($key, $replace);
});

Event Integration Use Laravel events for support workflows (e.g., TicketCreated):

// In a service provider
Event::listen(TicketCreated::class, function ($ticket) {
    // Send notification via Carbon-scheduled job
});

Configuration Quirks

Carbon Timezone Ensure the package uses Laravel’s timezone settings:

Support Laravel Package