softan / users-php-sdk
SDK PHP para Softan Users — gestion de usuarios y asociaciones de aplicacion
Requires
- php: >=8.1
- ext-curl: *
- ext-json: *
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Descripción
SDK oficial para integrar aplicaciones con Softan Users en PHP. Expone métodos estáticos de alto nivel para gestionar usuarios, asociaciones de aplicación y datos comunes (países, tipos de identificación).
Las credenciales de acceso a la API están embebidas en el SDK (sdk_meta.json). No se requiere ninguna configuración manual de API keys.
Requisitos
- PHP 8.1 o superior
- Composer 2
- Extensiones:
ext-curl,ext-json
Instalación
composer require softan/users-php-sdk:^0.2.8
Listo. No se necesita ningún paso adicional — las credenciales están embebidas.
Alternativa: instalación desde GitHub (VCS)
composer config repositories.softan-users vcs https://github.com/softansoluciones/softan-users-php-sdk composer require softan/users-php-sdk:dev-main
Quickstart
<?php require __DIR__ . '/vendor/autoload.php'; use SoftanUsers\Services; // Listar todos los usuarios (entorno stg por defecto) $users = Services::listUsers(); // Crear un usuario (solo nombre, apellido y correo son obligatorios) $created = Services::createUser([ 'user_name' => 'Juan', 'user_last_name' => 'Pérez', 'user_email' => 'juan@example.com', ]);
Uso en código
Users
use SoftanUsers\Services; // Listar todos los usuarios $list = Services::listUsers(); // Ver un usuario por ID $user = Services::showUser(42); // Crear usuario con todos los datos $created = Services::createUser([ 'user_name' => 'María', 'user_last_name' => 'García', 'user_email' => 'maria@example.com', 'identification_type' => 1, // Opcional: ID del tipo de identificación 'user_identification' => '987654', // Opcional: número de documento 'country_id' => 48, // Opcional: ID del país (Colombia) 'user_phone' => '+573001234567', // Opcional ]); // Crear usuario solo con los datos obligatorios $created = Services::createUser([ 'user_name' => 'Pedro', 'user_last_name' => 'Ruiz', 'user_email' => 'pedro@example.com', ]); // Actualizar usuario (requiere user_id, nombre, apellido, correo y user_status) $updated = Services::updateUser([ 'user_id' => 42, 'user_name' => 'María', 'user_last_name' => 'García', 'user_email' => 'maria@example.com', 'user_status' => 1, // 1=activo, 2=inactivo, 3=sin verificar 'country_id' => 49, // Opcional: si se envía, reemplaza el valor guardado ]); // Eliminar usuario $deleted = Services::deleteUser(42);
Campos opcionales (identification_type, user_identification, country_id, user_phone):
| Operación | Si no se envían (o van null / '') |
Si se envían con valor |
|---|---|---|
createUser |
Se guardan como NULL (sin información) |
Se guardan |
updateUser |
Se conserva el valor que ya tiene el usuario | Reemplazan el valor guardado |
Un campo ya guardado no se puede vaciar desde el SDK; solo reemplazar por otro valor.
Filtrar usuarios (server-side)
// Filtrado básico $result = Services::filterUsers([ 'filters' => ['user_status' => 1, 'user_email' => '%@softansol.com'], 'page' => 1, 'per_page' => 20, 'order_by' => 'created_at', 'order_dir'=> 'desc', ]); // $result['data']['users'] → array de usuarios // $result['data']['pagination'] → { page, per_page, total, total_pages }
Campos filtrables: user_id, identification_type, user_identification, user_name, user_last_name, user_email, user_phone, country_id, user_status, created_at (range), updated_at (range)
Modos de filtrado:
- Exacto:
'user_status' => 1 - LIKE:
'user_email' => '%@softansol.com' - IN:
'user_status' => [1, 2] - Rango:
'from_created_at' => '2025-01-01', 'to_created_at' => '2025-12-31'
Users Apps (asociaciones usuario-aplicación)
// Listar todas las asociaciones $associations = Services::listUserApps(); // Ver una asociación por ID $assoc = Services::showUserApp(10); // Crear asociación $created = Services::createUserApp([ 'user_id' => 42, 'app_identifier' => 'SOM-XXXX', ]); // Actualizar asociación $updated = Services::updateUserApp([ 'user_app_id' => 10, 'user_id' => 42, 'app_identifier' => 'SOM-XXXX', 'user_app_status' => 1, // 1=activo, 2=inactivo, 3=sin verificar ]); // Eliminar asociación $deleted = Services::deleteUserApp(10);
Filtrar asociaciones usuario-aplicación (server-side)
$result = Services::filterUserApps([ 'filters' => ['app_identifier' => 'SOM-65B', 'user_app_status' => 1], 'page' => 1, 'per_page' => 50, ]); // $result['data']['usersapps'] → array de asociaciones (incluye user_email, user_name) // $result['data']['pagination'] → { page, per_page, total, total_pages }
Campos filtrables: user_app_id, user_id, app_identifier, user_app_status, user_email, user_name, user_last_name, user_status, created_at (range), updated_at (range)
Commons
// Listar países disponibles $countries = Services::listCountries(); // Listar tipos de identificación $idTypes = Services::listIdentificationTypes();
Autenticación
Todas las operaciones del SDK (users, usersapps y datos comunes como países y tipos de identificación) usan el canal internal del API:
| Headers enviados | Uso |
|---|---|
X-API-KEY + X-App-Id |
Todos los métodos de Services::* |
Las credenciales (api_key y app_id) están embebidas en el SDK y se seleccionan automáticamente según el entorno activo. El SDK no usa la public_api_key del API.
Entornos
El SDK incluye credenciales para stg y prod. El entorno por defecto es stg.
El entorno activo se resuelve en este orden (mayor a menor prioridad):
| Prioridad | Mecanismo |
|---|---|
| 1 | SDK::$CONFIG['active_environment'] — override programático |
| 2 | sdk_config.json → active_environment — escrito por users-set-env.php |
| 3 | sdk_meta.json → default_environment (valor del paquete: stg) |
Opción A — CLI (recomendado)
php vendor/bin/users-set-env.php # interactivo
php vendor/bin/users-set-env.php --env=prod
php vendor/bin/users-set-env.php --env=stg
Escribe sdk_config.json en la raíz del proyecto. El cambio persiste entre requests y sobrevive composer update.
Opción B — Override programático
Útil cuando el entorno se determina en código (multi-tenant, flags de configuración, etc.). Debe ejecutarse antes de la primera llamada a Services::*.
use SoftanUsers\SDK; use SoftanUsers\Services; SDK::$CONFIG = ['active_environment' => 'prod']; $users = Services::listUsers();
TLS
La verificación TLS está habilitada por defecto. Para desarrollo puedes desactivarla por llamada:
Services::listUsers(null, false); // segundo parámetro: $verifyTLS Services::createUser($payload, null, false);
Compatibilidad
- PHP: 8.1+
- Sistemas: Windows, Linux, macOS
Desarrollo
composer install
composer test
CI: el workflow en .github/workflows/ci.yml valida Composer e integra PHPUnit en PHP 8.1/8.2/8.3.
Licencia
MIT (ver composer.json).