Mutlucell Laravel Package

Getting Started

1. Install the package with a constraint that matches your Laravel major:

   composer require ardakilic/mutlucell:^13.0
   

   As of 13.0.0 the package's major version is deliberately aligned with the Laravel major version it supports, so 13.x targets Laravel 13. If you are still on Laravel 9–12, stay on the corresponding older major (the last one before the jump was 9.0.0)—there is no 10.x, 11.x, or 12.x tag, so don't go hunting for one. Check the package's PHP constraint when upgrading; Laravel 13 itself requires PHP 8.3+.

   The service provider and Mutlucell facade are auto-discovered on Laravel 5.5+. On older versions, register Ardakilic\Mutlucell\MutlucellServiceProvider and alias the facade in config/app.php.

2. Publish the config and set your credentials in .env:

   php artisan vendor:publish --tag=config
   

   MUTLUCELL_USERNAME=your_api_username
   MUTLUCELL_PASSWORD=your_api_password
   MUTLUCELL_SENDER=YourApprovedSender
   

3. Look first at config/mutlucell.php to confirm the endpoint, sender ID, and any timeout/encoding options, then at the facade class itself—it is small and the methods map directly to Mutlucell’s XML endpoints. Nothing in the public API changed in 13.0.0; the release is a Laravel 13 compatibility bump plus the versioning change, so any existing integration code carries over untouched.

4. First use case—send a single SMS:

   use Ardakilic\Mutlucell\Facades\Mutlucell;
   
   $response = Mutlucell::send('Your order has shipped.', ['905551234567']);
   

   The sender ID (MUTLUCELL_SENDER) must already be approved in your Mutlucell account, and numbers should be in international format without a leading zero.

Implementation Patterns

• Notification channel. The most idiomatic integration is a custom Laravel notification channel so SMS becomes just another delivery method on your existing notifications:

  public function via($notifiable) { return [MutlucellChannel::class]; }
  
  public function toMutlucell($notifiable) {
      return MutlucellMessage::create("Reminder: {$this->appointment->time}")
          ->to($notifiable->phone);
  }
  

  Wrap Mutlucell::send() inside the channel’s send() method and forward the recipient’s phone number.

• Queue it. Treat the send as an outbound side effect. Dispatch a SendSms job with $tries/$backoff rather than calling the facade inside a request or notification synchronously. This gives you retries and keeps web responses fast.

• Service wrapper for testability. Don’t call the façade directly from controllers. Hide it behind an SmsSender interface and bind an implementation in the container. In tests, swap the binding for a fake that records calls—this avoids hitting Mutlucell during your test suite.

• Batch sends. Pass an array of recipients to a single send() call where the package supports it, or chunk large lists (100–500 numbers per job) and fan out with Bus::batch() so a single bad number doesn’t fail the whole run.

• Scheduled delivery. Mutlucell supports a send-date parameter; pass it through to schedule messages without holding a queue worker open. Keep the format in one place in your config so it matches what the XML expects.

• Operational visibility. Persist the returned message ID(s) and status code on your own sms_logs table, keyed by recipient and user. The provider’s delivery report lookup is only useful if you stored the ID at send time.

• Monitoring command. Schedule a daily artisan command that calls the credit-check method and alerts when balance drops below a threshold. Running out of credit is the most common silent failure mode for SMS.

• Upgrading the major. Because the version number now tracks Laravel, a bump from 9.0.0 to 13.0.0 reads like a huge change but is mostly a platform-support bump. Upgrade by raising the constraint in composer.json, running composer update ardakilic/mutlucell, and re-running php artisan config:cache. Still read the compare diff linked in the release notes—you are skipping four major numbers.

Gotchas and Tips

• Status codes are not exceptions. The API returns an XML response that is parsed into a result with a numeric status. A successful submission is typically 20; auth failures, invalid sender, and insufficient credit each return distinct codes. Always inspect the status and log the raw response on failure—otherwise sends fail silently.

• Phone number format is strict. Strip spaces, dashes, and the domestic trunk 0. Use 90… (country code) for Turkish numbers. Numbers that look valid locally will still be rejected by the API.

• Sender ID must be registered. A missing or unapproved sender returns an error from Mutlucell, not from Laravel. Validate it at boot (e.g., a config sanity check in a service provider) so it fails loudly during development.

• SMS length and encoding. Turkish characters (ş, ğ, İ, etc.) force UCS-2 encoding, dropping the per-segment limit from 160 to roughly 70 characters. Long messages are split into multiple segments and billed accordingly. Strip/transliterate where you can, and validate length before sending.

• No built-in retry or circuit breaker. Network errors and 5xx responses are your responsibility. Wrap the call in try/catch, only retry on transport errors (not on hard API rejections), and set a timeout so a hung HTTP call doesn’t stall a worker.

• Config caching bites. After running php artisan config:cache, the package reads cached values—changing .env without re-caching will leave you on stale credentials. Standard Laravel gotcha, but it shows up here as confusing auth errors.

• Version numbers mean "Laravel major", not package maturity. Since 13.0.0 the package major must match your framework major. Two consequences: constraints pinned as ^9.0 will silently keep you off Laravel 13, and a 13.x bump does not imply a breaking change to the package's own API. Check the changelog rather than assuming semver semantics.

• Lockstep versioning can strand you mid-cycle. There is no release published per Laravel minor, so a Laravel 13.1/13.2 upgrade won't produce a new package version—expect to stay on 13.x for the whole cycle, and don't wait on a package tag before upgrading Laravel itself.

• Testing the HTTP layer. If the package uses Guzzle under the hood, use Http::fake() and assert on the outgoing XML body. If it uses an internal client, the interface-swap pattern above is the reliable route—don’t rely on faking the facade alone.

• Idempotency. There is no dedupe at the provider. If a queued job runs twice (retry after a timeout where the first request actually succeeded), the user gets two messages. Guard with an idempotency key on your side or a sent_at check on the log row.

• Multi-tenancy. Sender IDs, credentials, and credit balances are per-account. If you serve multiple tenants, don’t rely on a single config file—instantiate or reconfigure the client per tenant, or bind a separately configured instance per tenant in the container.

• Extension point. The client is thin; the cleanest customization is to extend or decorate the main class and rebind it, rather than editing vendor code. Keep logging, retry, and normalization in your decorator—this also survives the periodic major bumps the lockstep versioning now guarantees.