Getting Started

Minimal Setup

Installation Add the package via Composer:

composer require chill-project/icpc2

Publish the config file (if available):

php artisan vendor:publish --provider="ChillProject\ICPC2\ICPC2ServiceProvider"

First Use Case The package appears to be a mirror of ICPC2 (likely a privacy-focused alternative to Google's Invisible reCAPTCHA). Start by:
- Checking the config/icpc2.php (if published) for basic configuration.
- Integrating the JavaScript snippet into your Blade views (likely via a helper or directive):
```
{!! ICPC2::render() !!}
```
- Validating form submissions with a middleware or service:
```
use ChillProject\ICPC2\Facades\ICPC2;

if (!ICPC2::verify($request->input('icpc2-token'))) {
    return back()->withErrors(['icpc2' => 'Verification failed']);
}
```
Where to Look First
- Documentation: Check the Framasoft repo for primary docs (this is a mirror).
- Service Provider: Inspect ICPC2ServiceProvider for registration logic.
- Facade: Review ICPC2 facade methods (render(), verify()) in src/Facades/ICPC2.php.
- Middleware: Look for VerifyICPC2 middleware if included.

Implementation Patterns

Common Workflows

Frontend Integration
- Blade Directives: Use @icpc2 or {{ icpc2() }} if the package provides them.
- Dynamic Rendering: Pass options to the renderer:
```
ICPC2::render(['theme' => 'dark', 'size' => 'compact']);
```
- Async Loading: Lazy-load the script to avoid blocking render:
```
@icpc2(['async' => true])
```

Backend Validation

Form Requests: Extend FormRequest to include ICPC2 validation:

public function rules()
{
    return [
        'icpc2-token' => 'required|icpc2',
    ];
}

Middleware: Protect routes with VerifyICPC2:

Route::middleware(['icpc2'])->group(function () {
    // Protected routes
});

Manual Verification: Use the facade in controllers:
```
if (ICPC2::verify($token)) {
    // Proceed
}
```

Configuration

Site Key: Set in config/icpc2.php:
```
'site_key' => env('ICPC2_SITE_KEY'),
```

Endpoint: Override the verification endpoint if needed:

'endpoint' => env('ICPC2_ENDPOINT', 'https://icpc2.example.com/api/verify'),

Event Handling

Listen for ICPC2 events (if supported) to log failures or trigger custom logic:

Event::listen('icpc2.failed', function ($request) {
    Log::warning('ICPC2 verification failed', ['ip' => $request->ip()]);
});

Integration Tips

Laravel Mix/Webpack: Bundle the ICPC2 script with your assets if customization is needed.

Caching: Cache the rendered script to reduce HTTP requests:

Cache::remember('icpc2-script', now()->addDays(1), function () {
    return ICPC2::render();
});

Testing: Mock the ICPC2 facade in unit tests:

ICPC2::shouldReceive('verify')->once()->andReturn(true);

Gotchas and Tips

Pitfalls

Archived Status
- The package is archived (mirror of Framasoft’s repo). Expect:
  - No active maintenance.
  - Potential breaking changes if the upstream project evolves.
- Workaround: Fork the repo and maintain your own branch if critical updates are needed.
Missing Documentation
- No built-in docs. Rely on:
  - Framasoft’s original repo (may have README/Wiki).
  - Code comments in src/ directory.
  - Method signatures in the ICPC2 facade.
Configuration Quirks
- Environment Variables: Ensure ICPC2_SITE_KEY is set in .env:
```
ICPC2_SITE_KEY=your_site_key_here
```
- Default Values: Some options may not be configurable (check config/icpc2.php defaults).
- Endpoint Overrides: If the package uses a custom verification endpoint, ensure it’s reachable from your server.
JavaScript Dependencies
- The package may rely on global variables or specific DOM elements. Avoid conflicts by:
  - Loading the script last in <body>.
  - Using a namespace if customizing the JS.

Rate Limiting

ICPC2 may throttle requests. Handle failures gracefully:

try {
    if (!ICPC2::verify($token)) {
        throw new \RuntimeException('ICPC2 verification failed');
    }
} catch (\Exception $e) {
    // Retry or show a fallback CAPTCHA
}

Debugging Tips

Log Verification Responses Add debug logging to the verify() method (temporarily):

\Log::debug('ICPC2 Response', [
    'token' => $token,
    'response' => $response,
]);

Check Network Requests
- Use browser dev tools to verify the ICPC2 script loads and the verification request completes.
- Look for errors in the Console or Network tabs.

Fallback Mechanism Implement a fallback (e.g., hCaptcha) if ICPC2 fails:

if (!ICPC2::verify($token)) {
    if ($request->has('hcaptcha-response')) {
        // Validate hCaptcha instead
    }
}

Clear Cache If changes to config aren’t reflected:
```
php artisan config:clear
php artisan view:clear
```

Extension Points

Custom Verification Logic Override the verification logic by binding a custom verifier:

$app->bind('icpc2.verifier', function () {
    return new CustomICPC2Verifier();
});

Add Custom Data Extend the verification payload:

ICPC2::verify($token, ['custom_field' => 'value']);

Create a Package Wrapper If the package lacks features, wrap it in a custom package to add:
- Additional config options.
- Event listeners.
- Middleware enhancements.
Contribute Upstream Since the package is archived, consider:
- Opening issues on the Framasoft repo.
- Submitting PRs for missing features or bugs.

Icpc2 Laravel Package