Weave Code
[READ-ONLY] Basic payment models and architecture for PHP e-commerce projects.
Frequently asked questions about Payment
- How do I integrate sylius/payment with Laravel’s Eloquent models?
- The package’s entities (Payment, PaymentMethod) map seamlessly to Laravel Eloquent models. Use `hasMany`/`belongsTo` relations for order-payment ties, and leverage Laravel’s migrations to adapt the Doctrine schema. For example, a `Payment` model can extend `Eloquent` with custom accessors for state transitions.
- Can I use Stripe or PayPal directly without Payum?
- Yes, but you’ll need to create custom adapters for Stripe/PayPal to bridge their SDKs with Sylius’s gateway interface. Payum is the default abstraction layer, but the component is gateway-agnostic. Check the [Payum documentation](http://payum.forma-dev.com/) for adapter patterns.
- What Laravel versions does sylius/payment support?
- The package targets PHP 8.0+ and Laravel 9.x/10.x. Verify compatibility by checking the [Sylius docs](https://docs.sylius.com/) for your Laravel version. For older versions (e.g., Laravel 8), you may need to pin dependencies or use a forked branch.
- How do I handle payment webhooks in Laravel?
- Use Laravel’s route model binding to validate webhook signatures (e.g., Stripe’s `webhook.signature`). Dispatch events like `PaymentCompleted` to trigger queue jobs (e.g., `PaymentProcessorJob`) or notifications. For idempotency, store webhook payloads in a `webhook_logs` table with a unique `signature` column.
- Does sylius/payment support multi-currency payments?
- Yes, the component natively handles multi-currency via the `Payment` entity’s `amount` and `currencyCode` fields. Ensure your Laravel app uses `setlocale()` for currency formatting and configure database collations (e.g., `utf8mb4_unicode_ci`) to avoid encoding issues.
- How do I test payment flows with mocked gateways?
- Use PHPUnit’s `createMock()` or Laravel’s `Mockery` to simulate payment gateways. For example, mock Payum’s `Capture` action to return `PaymentStatus::SUCCESS` in tests. Test event listeners with Laravel’s `fake()` method to assert dispatched events like `PaymentFailed`.
- What’s the best way to manage PCI compliance in Laravel?
- Avoid storing raw card data—use tokenization (e.g., Stripe tokens) or third-party vaults like HashiCorp Vault. Encrypt sensitive fields with Laravel’s `encrypt()` helper or packages like `spatie/laravel-encryption`. For PCI DSS, ensure your payment gateway is Level 1 certified and use their hosted fields.
- Can I extend payment states beyond ‘pending’, ‘completed’, or ‘failed’?
- Yes, customize the `PaymentStateMachine` to add states like `refunded` or `disputed`. Use Laravel’s `state()` method to transition payments and validate state changes with middleware. Document custom states in your API contracts (e.g., OpenAPI/Swagger).
- How do I offload payment processing to Laravel Queues?
- Create a `PaymentProcessorJob` that implements `ShouldQueue`. Dispatch it from your controller with `PaymentProcessorJob::dispatch($payment)`. Use Laravel’s `queue:work` to process jobs asynchronously. For retries, configure `retry_after` in the job’s `handle()` method.
- Are there alternatives to sylius/payment for Laravel?
- For simpler needs, consider `laravel-cashier` (Stripe/Braintree) or `spatie/payment-methods` (basic integration). For enterprise-grade DDD, Sylius offers deeper flexibility with Payum’s abstraction. If you need GraphQL, pair Sylius with `nuwave/lighthouse` for API-first workflows.
Weaver
How can I help you explore Laravel packages today?