Vordia Laravel Package

Getting Started

This release is additive — v1.7.0 adds a Melipayamak driver to the existing driver set. There are no breaking changes, so upgrades from v1.6.x should be a straight composer update.

1. composer require the package (or bump the constraint to ^1.7), then publish the config: php artisan vendor:publish --tag=... (check the package's service provider for the actual tag).
2. Open config/sms.php first — that is where the default driver, per-driver credential blocks, and any from/sender defaults live. This one file tells you most of what the package does.
3. Add the Melipayamak credentials to .env alongside the existing drivers, keeping the naming convention already used for the other gateways (typically SMS_MELIPAYAMAK_USERNAME, SMS_MELIPAYAMAK_PASSWORD, SMS_MELIPAYAMAK_FROM — verify against the driver's constructor).
4. First use case: point the default driver at melipayamak in a local or staging environment and send a single OTP to your own number before wiring it into any notification. This validates credentials, sender number, and phone-number formatting in one shot.

If you have never used the package, the fastest orientation is: read the config file, then the driver interface, then one existing driver implementation. Melipayamak will be structurally identical to the others, so comparing the two side by side is the cheapest way to learn the contract.

Implementation Patterns

Global default with per-send override. Keep a sane default in config/sms.php (SMS_DRIVER env) and override per call site only where a gateway genuinely differs by route or cost. Most teams end up with one provider per environment rather than mixing at runtime.

Notification channel integration. The idiomatic Laravel usage is a notification class implementing toSms() (or the package's equivalent) plus via(). This keeps SMS alongside mail and database channels and gets queueing, retries, and ShouldQueue for free. Prefer this over calling the facade directly from controllers.

Driver selection by config, not by if. Since the package is driver-based, the correct way to swap Melipayamak in or out is an env/config change. Hard-coding a driver name in application code defeats the abstraction and makes staging/production divergence painful.

Queue the send. SMS is a network call to a third party. Implement ShouldQueue on the notification, or wrap the facade call in a job, and add tries/backoff appropriate to the provider's tolerance for retries.

Testing seam. In php artisan test / CI, set the driver to the package's array/log driver (if one ships) or bind a fake into the container so no HTTP leaves the process. Combined with Notification::fake(), you can assert the notification was routed to SMS without touching Melipayamak.

Fallback chaining. If the package supports driver fallback, register Melipayamak as primary for Iranian numbers and a second gateway as backup. If it does not, implement fallback in a thin application-level service rather than forking the driver.

Gotchas and Tips

• Phone number format is the number-one failure mode. Melipayamak expects Iranian numbers in a specific shape (commonly 98xxxxxxxxxx without a leading + or 0). Normalise numbers at the boundary — a small cast or value object — before they reach the driver. Do not rely on the driver to be lenient.
• Pattern-based vs free-text sending. Iranian gateways typically distinguish "shared/service line" sends from pre-approved "pattern" sends where the text template is registered on the provider side and you only pass variables. Mixing these up produces confusing API errors. Check whether this driver exposes both and which one the notification channel uses by default.
• Credentials are not standardised. The new driver almost certainly introduces its own config keys. Copy the existing driver's env block shape, but do not assume SMS_USERNAME/SMS_PASSWORD are reused — a wrong key often manifests as a generic "authentication failed" from the provider rather than a Laravel error.
• Config caching. After changing driver or credentials, run php artisan config:clear in local and ensure your deploy pipeline caches config after env is in place. Stale cached config is the most common cause of "the driver change didn't take effect."
• Silent driver resolution failures. Most driver managers throw on an unknown driver name; some resolve to a null driver and silently no-op. Assert in a test that the configured default driver actually resolves, especially after an upgrade on a long-lived project.
• Log the provider response, not just the exception. Gateway-specific error codes (low credit, blacklisted number, invalid pattern) are frequently returned as a 200 with an error body. Capture response payload into the failure path so support can distinguish "our bug" from "customer's number is blocked."
• Extension point. If Melipayamak doesn't fit your needs, the driver contract is the stable extension point — write a custom driver and register it in the config's driver map rather than modifying vendor code. This keeps you upgradeable through future v1.x releases.
• Version pinning. Because drivers are added frequently, pin to ^1.7 and read release notes on each minor bump; additive driver releases are usually safe, but drivers occasionally ship with changed default timeouts or retry behaviour.