Weave Code
Laravel Laravel Package
omniconva/laravel
OmniConva for Laravel is a lightweight integration package that brings OmniConva services into Laravel applications, offering simple configuration, familiar Laravel conventions, and a clean starting point to help you add OmniConva-powered functionality quickly.
Connect a Laravel store to OmniConva: product sync, AI chat orders and webhooks in a few lines.
Frequently asked questions about Laravel
- How do I install OmniConva for Laravel?
- Install the package with Composer using composer require omniconva/laravel, then publish its configuration and migrations. Run the omniconva:install command to set up credentials and configuration, publish the migrations with the omniconva-migrations tag, and run php artisan migrate. The package supports Laravel 12 and 13 on PHP 8.2 or newer.
- Which Laravel and PHP versions does omniconva/laravel support?
- The support matrix is Laravel 12 and 13 with PHP 8.2 or higher. Laravel 10 and 11 applications are not supported. Check this before adding the package to an existing project, especially if you are still on an older Laravel release.
- How do I configure OmniConva in a Laravel app?
- Publish the package config and set the required values through environment variables, keeping secrets out of source control. The omniconva:install command reads configuration rather than env() directly, never blanks a credential, quotes values, and warns when secrets are passed as CLI options. This matters for config-cached deployments and helps avoid leaking secrets into shell history.
- Why does my webhook URL fail after upgrading to OmniConva 1.0.1?
- Version 1.0.1 requires OMNICONVA_WEBHOOK_URL to use https except for localhost and 127.x addresses, unless you explicitly set OMNICONVA_ALLOW_HTTP=1. Setups pointing at internal hostnames, Docker Compose service names, or TLS-terminating proxies over http will break on composer update. Redirects are also no longer followed, so an edge http-to-https redirect or load-balancer hop will fail silently; verify that the configured URL resolves directly.
- Do I need to run the second OmniConva migration?
- Yes. Publish the migrations with the omniconva-migrations tag and run php artisan migrate after upgrading. The second migration adds the owner-token column and the widened 255-character key used by the idempotency claims table, which protects against duplicate orders during retries and stalls. Skipping it leaves that protection incomplete.
- How should my order handler signal a refused order in OmniConva?
- Throw OmniConva\Laravel\Exceptions\OrderRefused when your order handler needs to signal a business refusal. This is the sanctioned contract, and only OrderRefused messages reach OmniConva. Any other exception is reported to your handler and answered with a generic 500, so your own logging and alerting become the diagnostic channel.
- Why are product sync errors no longer throwing exceptions?
- The SyncsWithOmniConva and SyncsParentWithOmniConva traits now report mapping and encoding problems instead of throwing, so a sync cannot abort a product save. Invalid UTF-8 is substituted rather than causing a fatal error, which can alter product text in transit without rejection. Availability improves, but catalog drift becomes silent unless you watch the reported exceptions.
- How does OmniConva for Laravel prevent duplicate orders during retries?
- Idempotency claims are database-backed and now use an owner token, so a stalled request cannot release or complete the claim that replaced it. That protects against duplicate orders during retries and stalls. The retention window and TTL for claims are still unspecified, so review your own cleanup and operational expectations.
- What happens to errors and customer data in OmniConva webhook responses?
- Only OrderRefused messages reach OmniConva; anything else, including a QueryException carrying SQL and customer data, is reported to your handler and answered with a generic 500. This closes a real PII-leak vector, but vendor-side visibility into failures drops to just 500. You must rely on your own logging and alerting for diagnosis.
- Is OmniConva for Laravel production-ready and what support is published?
- The package follows Laravel conventions and has a conventional integration surface, but several operational details remain unpublished: signature algorithm, canonicalization, clock-skew tolerance, replay window, secret rotation, webhook retry and dead-letter policy, product pagination and rate limits, multi-store and multi-currency support, deprecation policy, license, SLA, and data residency. Version 1.0.1 also shipped a breaking webhook URL change in a patch release, so treat patch updates carefully. It is a positive signal on responsiveness, but it is not a substitute for a published support contract.
Weaver
How can I help you explore Laravel packages today?