README

snow-driver

Plug-in Laravel fournissant un driver de base de données pour accéder aux objets d'une plateforme ServiceNow au travers de modèles Eloquent (API Table ServiceNow).

Fonctionnalités

Connexion et authentification Basic Auth vers une instance ServiceNow, avec abstraction Credentials pour permettre l'ajout futur d'autres modes (OAuth2 client credentials)
Client HTTP interne (TableApiClient) et hiérarchie d'exceptions dédiées (ServiceNowConnectionException, ServiceNowAuthenticationException, ServiceNowApiException, ServiceNowMalformedResponseException)
Modèle Eloquent de base (ServiceNowModel) mappant sys_id (clé primaire string) et sys_created_on/sys_updated_on sur les timestamps natifs Eloquent
Query builder traduisant where, whereIn, whereNull, whereBetween, orderBy, limit/offset en sysparm_query et paramètres sysparm_* de l'API Table, avec pagination automatique transparente pour all()/get()
Comptage (count(), paginate()) via la fonction d'agrégation de l'API ServiceNow, sans rapatrier les enregistrements, et test d'existence (exists()) borné à un enregistrement
Introspection du schéma via Schema::connection() (liste des tables, colonnes typées, clés étrangères déduites des champs de référence) lue dans le dictionnaire de l'instance, avec cache applicatif configurable (schéma, comptage, liste des tables) pour les tables déclarées en génération de modèles
Génération automatique de modèles Eloquent (servicenow.models.tables) au démarrage de l'application hôte : $fillable/$casts déduits du dictionnaire, relations belongsTo/hasMany générées entre tables configurées
ServiceNowUnsupportedQueryException pour toute clause du query builder sans équivalent ServiceNow (join, groupBy, agrégats autres que le comptage, sous-requêtes, etc.)

Prérequis

PHP ^8.2
Laravel 11, 12 ou 13 (illuminate/database, illuminate/http, illuminate/support)
Service Now Zurich

Installation

composer require quatrebarbes/snow-driver

Le service provider Quatrebarbes\SnowDriver\ServiceNowServiceProvider est auto-découvert par Laravel.

Publier la configuration :

php artisan vendor:publish --tag=servicenow-config

Configuration

La connexion ServiceNow se déclare comme une connexion Laravel classique dans config/servicenow.php (ou directement dans config/database.php) :

'servicenow' => [
    'driver' => 'servicenow',
    'database' => '',
    'base_url' => env('SNOW_BASE_URL'),
    'timeout' => env('SNOW_TIMEOUT', 30),
    'auth' => [
        'mode' => env('SNOW_AUTH_MODE', 'basic'),
        'username' => env('SNOW_USERNAME'),
        'password' => env('SNOW_PASSWORD'),
    ],
],

Variables d'environnement correspondantes :

Variable	Description	Défaut
`SNOW_CONNECTION`	Nom de la connexion par défaut	`servicenow`
`SNOW_BASE_URL`	URL de base de l'instance ServiceNow	—
`SNOW_TIMEOUT`	Timeout HTTP en secondes	`30`
`SNOW_AUTH_MODE`	Mode d'authentification	`basic`
`SNOW_USERNAME` / `SNOW_PASSWORD`	Identifiants Basic Auth	—
`SNOW_PAGE_SIZE`	Taille de page pour la pagination automatique (`all()`/`get()` sans limite explicite)	`10000`
`SNOW_MODELS_NAMESPACE`	Namespace PHP des modèles générés (`servicenow.models.tables`)	`App\Models`
`SNOW_SCHEMA_CACHE_TTL`	Durée de validité (secondes) du cache de schéma/comptage/liste des tables ; `0` désactive le cache	`3600`

La connexion est paresseuse : aucune requête n'est effectuée au boot de l'application, seulement à la première interrogation.

Utilisation

use Quatrebarbes\SnowDriver\Eloquent\ServiceNowModel;

class Incident extends ServiceNowModel
{
    protected $connection = 'servicenow';
    protected $table = 'incident';
}

Incident::where('active', true)
    ->orderBy('sys_created_on', 'desc')
    ->limit(20)
    ->get();

Introspection du schéma

Une connexion ServiceNow répond aux mêmes interrogations de schéma qu'une connexion SQL, lues dans le dictionnaire de l'instance (sys_db_object, sys_dictionary) : un outil Laravel générique d'exploration de données fonctionne donc sur une connexion ServiceNow sans rien connaître du driver.

use Illuminate\Support\Facades\Schema;

$schema = Schema::connection('servicenow');

$schema->getTableListing();              // noms techniques des tables de l'instance
$schema->hasTable('incident');
$schema->getColumns('incident');         // champs hérités des tables parentes compris
$schema->getColumnListing('incident');
$schema->hasColumn('incident', 'number');
$schema->getForeignKeys('incident');     // déduites des champs de type reference

Incident::count();                       // fonction d'agrégation de l'API, sans rapatriement
Incident::paginate(20);                  // total et nombre de pages inclus
Incident::where('active', true)->exists();

Les types internes ServiceNow sont exposés sous les noms de types que Laravel reconnaît (boolean, integer, decimal, date, datetime, time, json, text, varchar) ; un type inconnu est exposé comme chaîne plutôt que de faire échouer l'introspection. Un champ de type reference est exposé comme clé étrangère vers sys_id de la table référencée — mais ServiceNow n'appliquant aucune contrainte d'intégrité référentielle, cette clé est descriptive.

La structure d'une table ServiceNow se modifie côté instance : les opérations de modification de schéma (Schema::create(), drop(), table()...) lèvent ServiceNowUnsupportedQueryException.

Pour les tables déclarées dans servicenow.models.tables (voir Génération automatique de modèles ci-dessous), ainsi que pour la liste des tables de l'instance, le schéma et le comptage sont mis en cache (SNOW_SCHEMA_CACHE_TTL) : une entrée expirée est servie telle quelle et rafraîchie de façon asynchrone après la réponse en cours, sans pénaliser la lecture qui l'a déclenchée.

Génération automatique de modèles

Déclarer les tables ServiceNow à modéliser dans config/servicenow.php :

'models' => [
    'tables' => ['incident', 'sys_user', 'task'],
    'namespace' => env('SNOW_MODELS_NAMESPACE', 'App\\Models'),
],

Au démarrage de l'application hôte, un fichier de modèle Eloquent est généré (s'il n'existe pas déjà) pour chaque table déclarée : $table, $fillable (champs modifiables, champ display puis mandatory en tête, virtuels exclus) et $casts déduits du dictionnaire ServiceNow, relations belongsTo()/hasMany() générées entre les tables configurées. Un fichier déjà présent n'est jamais réécrit (personnalisation manuelle préservée).

Application de démonstration

Le dossier demo/ contient une application Laravel de démonstration (Blade, sans front JS) illustrant l'usage du driver : menu des tables ServiceNow configurées, liste paginée, détail d'un enregistrement, page d'erreur illustrant la hiérarchie d'exceptions.

Lancement via Docker :

docker compose up --build

L'application est alors disponible sur http://localhost:8000. Voir demo/README.md pour la configuration détaillée.

Tests

composer install
vendor/bin/phpunit

Les tests sont organisés en tests/Unit (une fonction = un test) et tests/Feature (un test par comportement/endpoint), via Orchestra Testbench.

Documentation

Spécifications fonctionnelles détaillées : docs/sfd/ — driver, génération de modèles, introspection du schéma
Plan de développement et avancement : docs/roadmap.md

Licence

MIT

quatrebarbes / snow-driver

Maintainers

Package info

Statistics

Security