Getting Started

Minimal Steps

Installation: Download IronCore.class.php from the repository and place it in your Laravel project’s app/Utils/ directory (or a similar location). No Composer dependency is required, but you can use the official package via:
```
composer require iron-io/iron_core
```
(Note: The package is a single-file utility, so manual inclusion is straightforward.)

First Use Case: Use IronCore to handle authentication, HTTP requests, or payload formatting for Iron.io APIs (e.g., IronWorker, IronMQ). Example:

use IronCore\IronCore;

// Initialize with Iron.io API token
$ironCore = new IronCore(['token' => 'your_iron_io_token']);

// Send a job to IronWorker
$response = $ironCore->request('POST', 'https://worker.iron.io/1/jobs', [
    'json' => [
        'command' => 'php /path/to/script.php',
        'timeout' => 30
    ]
]);

$jobData = $ironCore->parseJson($response->getBody());

Where to Look First:
- Source Code: Focus on IronCore.class.php. Key methods include:
  - request(): Handles HTTP requests with built-in retry logic.
  - parseJson(): Safely decodes JSON responses.
  - handleError(): Standardizes error responses from Iron.io APIs.
- Laravel Integration: Extend IronCore to work with Laravel’s service container or HTTP client for seamless adoption.

Implementation Patterns

Usage Patterns

Authentication Handling: Use IronCore to manage API tokens and signing for Iron.io services. Example:

$ironCore = new IronCore([
    'token' => config('services.iron_io.token'),
    'project_id' => config('services.iron_io.project_id')
]);

// Automatically includes auth headers in requests
$response = $ironCore->request('GET', 'https://mq.iron.io/1/projects');

Request Retries: Leverage built-in retry logic for transient failures (e.g., network issues). Configure retries via:
```
$ironCore = new IronCore([
    'retry_count' => 3,
    'retry_delay' => 1000 // milliseconds
]);
```

Payload Formatting: Standardize JSON/XML payloads for Iron.io APIs. Example:

$payload = [
    'command' => 'php artisan queue:work',
    'env' => ['QUEUE_CONNECTION' => 'ironmq']
];
$response = $ironCore->request('POST', 'https://worker.iron.io/1/jobs', [
    'json' => $payload
]);

Error Handling: Use IronCore's error parsing to convert Iron.io API errors into Laravel-friendly exceptions:

try {
    $response = $ironCore->request('GET', 'https://invalid.endpoint');
} catch (\IronCoreException $e) {
    Log::error('Iron.io API Error: ' . $e->getMessage());
    // Handle specific Iron.io errors (e.g., 404, 401)
}

Integration with Laravel Services: Create a Laravel service class to wrap IronCore for better organization:

namespace App\Services;

use IronCore\IronCore;

class IronWorkerService {
    protected $ironCore;

    public function __construct() {
        $this->ironCore = new IronCore([
            'token' => config('services.iron_io.token')
        ]);
    }

    public function sendJob(array $payload) {
        return $this->ironCore->request('POST', 'https://worker.iron.io/1/jobs', [
            'json' => $payload
        ]);
    }
}

Middleware for Global Use: Extend IronCore to work with Laravel middleware for consistent API calls:

namespace App\Http\Middleware;

use Closure;
use IronCore\IronCore;

class IronApiMiddleware {
    public function handle($request, Closure $next) {
        $ironCore = new IronCore(['token' => config('services.iron_io.token')]);
        // Attach IronCore instance to the request or use it globally
        $request->merge(['ironCore' => $ironCore]);
        return $next($request);
    }
}

Workflows

IronMQ Integration: Use IronCore to publish/subscribe messages:

$message = ['task' => 'process_order', 'order_id' => 123];
$response = $ironCore->request('POST', 'https://mq.iron.io/1/projects/{project_id}/queues/{queue_name}/messages', [
    'json' => $message
]);

IronCache Integration: Simplify cache operations with IronCore:

$response = $ironCore->request('POST', 'https://cache.iron.io/1/keys', [
    'json' => [
        'key' => 'user:123',
        'value' => json_encode(['name' => 'John']),
        'ttl' => 3600
    ]
]);

Webhook Validation: Validate incoming Iron.io webhooks using IronCore's signature verification:

$signature = $request->header('X-Iron-Signature');
$payload = $request->getContent();
if (!$ironCore->validateWebhook($payload, $signature)) {
    abort(403, 'Invalid webhook signature');
}

Integration Tips

Laravel Service Container: Bind IronCore to the container for dependency injection:

$this->app->singleton(IronCore::class, function ($app) {
    return new IronCore([
        'token' => $app['config']['services.iron_io.token']
    ]);
});

Config Publishing: Publish IronCore configuration to config/iron_core.php:

// In a ServiceProvider
$this->publishes([
    __DIR__ . '/config/iron_core.php' => config_path('iron_core.php'),
]);

Testing: Mock IronCore in Laravel tests:

$mockIronCore = Mockery::mock(IronCore::class);
$mockIronCore->shouldReceive('request')
    ->once()
    ->andReturn((object) ['body' => '{"status": "success"}']);

$this->app->instance(IronCore::class, $mockIronCore);

Logging: Extend IronCore to log requests/responses:

$ironCore = new IronCore([
    'token' => config('services.iron_io.token'),
    'logger' => function ($message) {
        Log::debug('Iron.io API: ' . $message);
    }
]);

Gotchas and Tips

Pitfalls

No Composer Support (Manual Inclusion):
- The package lacks a Composer autoloader, so you must manually include IronCore.class.php or use the iron-io/iron_core package (which wraps the class).
- Workaround: Use the Composer package and autoload the class via psr-4 in composer.json:
```
"autoload": {
    "psr-4": {
        "IronCore\\": "vendor/iron-io/iron_core/src/"
    }
}
```
PHP Version Compatibility:
- The package supports PHP 5.2+, but Laravel requires PHP 8.0+. Test for compatibility with:
  - Named arguments.
  - Typed properties.
  - Constructor property promotion.
- Workaround: Use a wrapper class to adapt IronCore to PHP 8.x features.
Error Handling Quirks:
- IronCore throws IronCoreException for errors, which may not integrate seamlessly with Laravel’s exception hierarchy.
- Workaround: Catch and rethrow exceptions as Laravel-specific types:
```
try {
    $response = $ironCore->request('GET', 'https://invalid.endpoint');
} catch (\IronCoreException $e) {
    throw new \HttpException(400, $e->getMessage());
}
```
No Native Laravel HTTP Client Integration:
- IronCore does not natively integrate with Laravel’s Http facade or Guzzle. You’ll need to wrap it or use it alongside Laravel’s client.
- Workaround: Use IronCore for Iron.io-specific logic and Laravel’s Http client for other APIs:
```
$response = $ironCore->request('POST', '
```

Iron Core Laravel Package