Getting Started

This bundle is a thin Symfony integration around the SerwerSMS.pl API v2 PHP client. Treat it as a legacy integration layer: confirm the bundle supports your Symfony/PHP version before adopting it, and expect to read the underlying client classes rather than rely on extensive bundle documentation.

Minimal setup:

Install with Composer:

composer require serwersms/serwersmsbundle

Symfony 2/3: add it to app/AppKernel.php.

$bundles = [
    // ...
    new SerwerSMS\SerwerSMSBundle\SerwerSMSBundle(),
];

Symfony 4: add it to config/bundles.php.

return [
    // ...
    SerwerSMS\SerwerSMSBundle\SerwerSMSBundle::class => ['all' => true],
];

Configure API credentials. The exact key layout depends on the bundle version, but it follows the normal Symfony bundle pattern:

# config/packages/serwersms.yaml (Symfony 4)
# or app/config/config.yml (Symfony 2/3)
serwer_sms:
    username: '%env(SERWERSMS_USERNAME)%'
    password: '%env(SERWERSMS_PASSWORD)%'

Discover the actual service ID before writing code:
```
bin/console debug:container serwer
bin/console debug:container --tag=serwersms
```
Look for the client service exposed by the bundle, then inject it into a controller, command, or your own service.

First use case: send a single transactional SMS from a Symfony command. Inject the bundle client, call its message-sending API, log the response, and verify delivery separately using the client’s status/check method. Do this in a command before wiring it into user-facing flows so you can validate credentials, sender name, and phone-number formatting safely.

Implementation Patterns

Inject the bundle client, then wrap it. Do not scatter direct client calls through controllers. Create a small application service such as SmsSender that depends on the bundle client, normalizes phone numbers, chooses the sender name, and translates API responses into your domain result.

final class SmsSender
{
    public function __construct(private $serwerSmsClient)
    {
    }

    public function send(string $phone, string $text): void
    {
        $response = $this->serwerSmsClient->messages->send([
            'phone' => $phone,
            'text' => $text,
            'sender' => 'MyApp',
        ]);

        // Map response/error codes to your own exceptions or result object.
    }
}

Use it for common SMS workflows:

Single transactional messages: OTPs, order confirmations, password-reset codes.
Bulk sends: import recipients from CSV, validate and de-duplicate locally, then use the client’s bulk API rather than looping over single sends.
Delivery tracking: persist the message ID returned by the API and poll the status/check endpoint from a console command or scheduled job.
Contact/group management: sync application users or segments to SerwerSMS contacts and groups when SMS campaigns are part of the product.
Sender-name management: query and manage sender names through the client if your account supports it.

Keep API calls out of the request cycle when possible. SMS gateways are external dependencies. For non-critical messages, dispatch a Symfony Messenger message or write to an outbox table and process it from a worker. For OTPs, send synchronously but set short HTTP/guzzle timeouts and handle failure explicitly.

Normalize inputs before calling the API. Store phone numbers in E.164 format where possible. Keep sender names in configuration, not hard-coded in multiple services. Validate message length and encoding locally to avoid surprise multi-part SMS costs.

Persist the provider response. Save the external message ID, status, timestamp, recipient, and raw response. This is essential for support, reconciliation, and retry logic.

Test behind an interface. Since the bundle exposes a concrete client, define your own SmsGateway interface and adapt the SerwerSMS client to it. In tests, replace the adapter with a fake. This also makes it easier to migrate away from the bundle later.

Gotchas and Tips

This is a legacy, low-usage bundle. The last release was in 2019 and it targets Symfony 2/3/4. Check PHP and Symfony version constraints before installing. On modern Symfony versions, prefer the standalone serwersms/php-client package and wire it yourself.
Verify the service ID and config key. Bundle naming conventions vary. Run debug:container and debug:config rather than guessing. If the bundle’s services are private under Symfony 4, inject them via constructor autowiring or define an alias in your own services.yaml.
Do not commit credentials. Use environment variables or Symfony secrets. The bundle config may accept username/password directly, so ensure the resolved parameters are not dumped into logs or cached config artifacts.
Sender names must be registered and approved with SerwerSMS.pl. A send can fail even when credentials are correct if the sender field is missing, unapproved, or unsupported for the account.
Phone-number format matters. Test with real international formats, including the Polish +48 prefix. Validate locally and avoid assuming the API will normalize arbitrary input.
Handle API errors as data, not just exceptions. The underlying client may return arrays with status/error codes rather than throwing. Inspect the response shape and map known error codes to retryable versus permanent failures.
Bulk versus looped sends. Sending thousands of individual requests is slow, expensive, and likely rate-limited. Use the bulk endpoint, batch conservatively, and add backoff for transient failures.
Delivery reports are asynchronous. A successful send response usually means “accepted,” not “delivered.” Poll status endpoints and store the final state.
Watch multi-part SMS costs. Long or non-GSM-encoded messages split into multiple SMS parts. Validate length and encoding before sending, especially for OTP and transactional templates.
Debugging tip: enable Symfony’s HTTP client/profiler logging if the underlying client uses Guzzle, or wrap the client in a decorator that logs request metadata and response codes. Never log full credentials or full message contents containing personal data.
Extension point: decorate the bundle’s client service with your own class implementing the same methods, or alias the bundle service to an interface. This lets you add logging, retries, metrics, and test doubles without modifying vendor code.
Plan an exit path. Because the bundle is effectively unmaintained, keep SerwerSMS calls isolated behind one adapter. Migrating to the official PHP client or another provider should be a service swap, not a codebase-wide rewrite.

Serwersmsbundle Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips