README.md

Cliente de Háblame SMS (Colombia) para PHP (Optimizado para Laravel)

Este paquete facilita la conexión con la API de Háblame SMS para enviar mensajes de texto y consultar el saldo. Además, permite el envío de notificaciones a través de SMS usando el sistema de notificaciones de Laravel.

Requerimientos

• PHP >= 7.1
• Laravel >= 5.3 (Requerido solo si vas a usar la fachada o el canal de notificaciones).

Instalación

Puedes instalar el paquete a través de composer:

composer require andreshg112/hablame-sms

Uso

/**
 * Crear instancia.
 *
 * $client: Número de cliente.
 * $api: Clave de la API.
 * $guzzle: [opcional] Sirve para pasar un cliente de Guzzle (\GuzzleHttp\Client) configurado,
 * por ejemplo, en pruebas unitarias.
 */
$hablame = new \Andreshg112\HablameSms\Client($client, $api, $guzzle);

/**
 * Consultar saldo.
 *
 * Retorna un array con la respuesta del servidor de Háblame.
 */
$response = $hablame->checkBalance();

/**
 * Enviar mensaje.
 *
 * $phoneNumbers: Número(s) telefónico(s) separados por coma.
 * $sms: Cuerpo del mensaje.
 * $datetime: [opcional] Fecha a enviar el mensaje. Formato en PHP: 'Y-m-d H:i:s'
 * $referencia: [opcional] Nombre de campaña.
 *
 * Retorna un array con la respuesta del servidor de Háblame.
 */
$response = $hablame->sendMessage($phoneNumbers, $sms, $datetime, $reference);

Laravel

Fachada y alias

En Laravel puedes usar la fachada o el alias para ejecutar las funciones anteriores. Primero debes agregar las credenciales de Háblame a config/services.php así:

return [
    // ...
    'hablame_sms' => [
        'api' => env('HABLAME_API', ''),
        'cliente' => env('HABLAME_CLIENTE', ''),

        /**
         * Si deseas agregar tu propio cliente de Guzzle, en vez de usar uno por defecto,
         * haz que el callback retorne el respectivo cliente.
         * Si quieres usar uno por defecto, quita este parámetro o asígnalo null.
         */
        'guzzle' => function (): \GuzzleHttp\Client {
            return createHttpClient(logger());
        },
    ],
    // ...
];

Ahora puedes hacer:

$response = \Andreshg112\HablameSms\Facade::checkBalance();

$response = \Andreshg112\HablameSms\Facade::sendMessage($phoneNumbers, $sms, $datetime, $reference);

// o

$response = \Hablame::checkBalance();

$response = \Hablame::sendMessage($phoneNumbers, $sms, $datetime, $reference);

Si usas Laravel < 5.5, debes agregar \Andreshg112\HablameSms\HablameSmsServiceProvider::class al arreglo de providers en config/app.php.

Notificaciones

Puedes enviar notificaciones usando el sistema integrado en Laravel que facilita el proceso y organiza el código. Ten en cuenta que debes saber implementar las notificaciones de Laravel antes de usar esta funcionalidad.

En tu notificación, añade HablameChannel::class al array que retorna la función via():

use Andreshg112\HablameSms\HablameChannel;

public function via($notifiable)
{
    return [HablameChannel::class];
}

Luego, crea un método llamado toHablameNotification() en tu clase:

use Andreshg112\HablameSms\HablameMessage;

public function toHablameNotification($notifiable)
{
    return (new HablameMessage)
        ->phoneNumbers($phoneNumbers)
        ->sms($sms)
        ->datetime($datetime)
        ->reference($reference);

    // o

    return new HablameMessage($phoneNumbers, $sms, $datetime, $reference);
}

Pruebas

composer test

Registro de cambios

Por favor mira el historial de versiones para más información sobre lo que ha cambiado recientemente.

Contribuir

Por favor mira las guías de contribución (en inglés) para conocer los detalles.

Seguridad

Si descubres alguna vulnerabilidad, por favor escríbeme a andreshg112@gmail.com en vez de usar el seguimiento de indicendias de GitHub.

Créditos

• Andrés Herrera García
• Todos los colaboradores

Licencia

La Licencia MIT. Por favor mira el archivo de licencia para más información.

PHP Package Boilerplate

This package was generated using the PHP Package Boilerplate.