Mellat Laravel Package

Getting Started

Start by checking the package README, composer.json, service provider, published config, and any registered routes. Since 0.1.2 fixes wrong redirection after payment, prioritize the payment callback/success/cancel flow before building around the package.

Minimal setup:

1. Install and publish package assets/configuration:

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\\<Package>\\ServiceProvider"
   

2. Configure payment credentials and redirect targets in .env.
3. Clear cached config/routes after changing redirect URLs:

   php artisan config:clear
   php artisan route:clear
   

4. Run php artisan route:list and identify the package routes for payment initiation, callback, success, cancel, and webhook handling.
5. Build the first use case around a simple checkout: initiate payment, store the pending payment/order reference, handle the provider return, verify status, then redirect to the correct confirmation or failure page.

In 0.1.2, specifically verify that successful payments land on the intended post-payment page and that cancelled/failed payments return to checkout or a failure route without losing context.

Implementation Patterns

Use the package as the payment orchestration layer, but keep order fulfillment and redirect decisions in application code.

• Store context before redirecting to the provider. Save the order ID, payment reference, user/guest identifier, and intended success/cancel URLs before sending the customer to the payment provider.
• Prefer named routes over hard-coded URLs. Redirect configuration should resolve through route('checkout.success', ...) or a dedicated redirect resolver where possible. This avoids environment-specific URL bugs.
• Treat the browser redirect as UX, not fulfillment. The return from the provider should verify payment status and redirect the user, but order fulfillment should be confirmed via webhook or server-to-server status check.
• Handle success, cancel, and failure separately. Do not assume every provider return is successful. Check the provider status/reference before showing a confirmation page.
• Use a pending/payment record. Create a local payment record before redirecting, then update it on callback/webhook. This makes idempotency and debugging much easier.
• Integration tip: If the package dispatches events or exposes a redirect resolver, hook into those instead of editing vendor code. Publishable config and container bindings are the preferred extension points.
• For 0.1.2: Add or update tests that assert the final redirect target after a successful payment, a cancelled payment, and a failed payment. Use the provider’s sandbox/test mode and assert relative paths or route names where possible.

Example workflow:

// 1. Create order/payment record
$payment = Payment::create([...]);

// 2. Initiate payment through the package
return $package->redirectToProvider($payment);

// 3. On return/callback, verify status before redirecting
if ($payment->isSuccessful()) {
    return redirect()->route('checkout.success', $payment->order);
}

return redirect()->route('checkout.cancel', $payment->order);

If the package owns the redirect, configure its success/cancel URLs explicitly and keep them aligned with your route names and middleware.

Gotchas and Tips

• 0.1.2 is a redirect bugfix. After upgrading, re-test the full payment flow in the target environment. A stale config cache or route cache can make the fix appear not to work.
• Clear caches after deployment. Run php artisan config:clear and php artisan route:clear, or rebuild caches deliberately with config:cache and route:cache.
• Check for hard-coded redirect URLs. Wrong redirection often comes from absolute URLs, mismatched route names, trailing-slash differences, or environment values left over from staging.
• Watch provider-appended query parameters. Some providers append status, token, or payment identifiers to the return URL. Ensure your route and middleware accept those parameters and do not redirect-loop.
• Session loss can look like a redirect bug. If the customer is not authenticated after returning from the provider, check session domain, SameSite cookie settings, and guard configuration.
• Do not trust the return URL for fulfillment. Verify the payment status server-side before marking an order paid. Redirect correctness is not proof of payment.
• Validate redirect targets. If success/cancel URLs are user-supplied or configurable, restrict them to an allowlist to avoid open-redirect issues.
• Use webhooks for durable state changes. Queue webhook processing, verify signatures, and make handlers idempotent.
• Pin the version while on 0.x. Early releases can change behavior. Review changelogs before upgrading and keep payment tests in CI.
• Debugging checklist: inspect config('...'), run php artisan route:list, log the provider return payload, confirm the local payment record status, and test with the provider sandbox. Laravel Telescope or structured logs are useful for tracing the callback/redirect path.