README

Bibliothèque PHP pour faciliter l'appel de fonctions et procédures stockées Oracle via Doctrine.

Installation

composer require amsom-habitat/oracle-function-calling

Fonctionnalités

✅ Appel simple de fonctions Oracle
✅ Gestion automatique des paramètres CLOB volumineux
✅ Support des fichiers base64 convertis en BLOB Oracle
✅ Validation de la taille des fichiers
✅ Génération de réponses HTTP Symfony

Configuration

Symfony (Recommandé)

# config/services.yaml
services:
    AmsomUtilities\OracleFunctionCalling: ~

# config/services.yaml OPTION 2
services:
    AmsomUtilities\OracleFunctionCalling:
        arguments:
            $managerRegistry: '@doctrine'
            $fileMaxSize: 10485760  # Optionnel : 10MB par défaut

Variable d'environnement (Alternative)

FILE_MAX_SIZE=10485760  # 10MB en octets

Utilisation

Appel simple de fonction

use AmsomUtilities\OracleFunctionCalling;

class MyController
{
    public function __construct(
        private OracleFunctionCalling $oracleCaller
    ) {}
    
    public function myAction()
    {
        $result = $this->oracleCaller->call(
            'MY_PACKAGE.MY_FUNCTION',
            "'param1', 123, 'param2'"
        );
        
        // $result contient la chaîne JSON retournée par Oracle
        $data = json_decode($result);
    }
}

Appel avec paramètre CLOB volumineux

Pour passer de grandes chaînes (JSON volumineux, XML, etc.) qui dépassent 32000 caractères :

$largeJsonString = json_encode($bigData);

$result = $this->oracleCaller->largeCall(
    'MY_PACKAGE.PROCESS_LARGE_DATA',
    "'user123', 'action'",  // Paramètres avant le CLOB
    $largeJsonString,        // Le contenu volumineux
    "'additional_param'"     // Paramètres après (optionnel)
);

Note : Les virgules de séparation sont gérées automatiquement.

Appel avec fichier base64

Pour envoyer un fichier encodé en base64 qui sera converti en BLOB Oracle :

$base64File = base64_encode(file_get_contents('/path/to/file.pdf'));

$result = $this->oracleCaller->fileCall(
    'MY_PACKAGE.SAVE_DOCUMENT',
    "'DOC123', 'user@example.com', 'contract.pdf'",
    $base64File,
    ""  // Paramètres après (optionnel)
);

// Vérifier si le fichier est trop volumineux
$decoded = json_decode($result);
if (isset($decoded->error)) {
    // Gérer l'erreur de taille
}

Gestion de la réponse HTTP

use Symfony\Component\HttpFoundation\Response;

public function createAction(Request $request)
{
    $result = $this->oracleCaller->call(
        'MY_PACKAGE.CREATE_ITEM',
        "'param1', 'param2'"
    );
    
    // Génère automatiquement une Response HTTP
    // 201 si succès (présence de la propriété 'data' dans le JSON)
    // 400 si erreur
    return $this->oracleCaller->handleResult($result, Response::HTTP_CREATED);
}

Convention Oracle : La fonction doit retourner un JSON avec data pour indiquer un succès :

{"data": {"id": 123, "message": "Créé avec succès"}}

En cas d'erreur, retourner un JSON sans data :

{"error": "Message d'erreur", "code": "ERR_001"}

Configuration avancée

Configuration au constructeur

// Taille de fichier personnalisée (20MB)
$oracleCaller = new OracleFunctionCalling($managerRegistry, 20971520);

Configuration dynamique

// Modifier la taille max (avec chaînage)
$oracleCaller->setFileMaxSize(5 * 1024 * 1024)
             ->fileCall('SAVE_DOC', "'id'", $file, "");

// Récupérer la taille configurée
$maxSize = $oracleCaller->getFileMaxSize();

Constantes disponibles

OracleFunctionCalling::CLOB_CHUNK_SIZE         // 32000 (32 KB)
OracleFunctionCalling::RESPONSE_SIZE_LARGE     // 32000 (32 KB)
OracleFunctionCalling::RESPONSE_SIZE_STANDARD  // 4000 (4 KB)
OracleFunctionCalling::DEFAULT_FILE_MAX_SIZE   // 10485760 (10 MB)
// OracleFunctionCalling::MAX_CLOB_SIZE        // 52428800 (50 MB) - disponible mais commentée

Considérations de performance

Pour éviter les dépassements mémoire PHP :

Fichiers : Limite par défaut de 10 MB (configurable). Un fichier de 10 MB peut consommer jusqu'à 40-50 MB de mémoire pendant le traitement.
Paramètres CLOB : Pas de limite imposée par défaut. Pour de très gros volumes (>50 MB), assurez-vous d'avoir un memory_limit PHP suffisant (256 MB minimum recommandé).
Réponses JSON : Limitées à 32 KB (appels simples) ou 4 KB (CLOB/fichiers).

Recommandation : Configurez memory_limit = 256M dans php.ini pour une utilisation standard.

Activation de la validation CLOB (optionnel)

Si vous souhaitez imposer une limite stricte sur les paramètres CLOB pour éviter les dépassements mémoire, vous pouvez :

Décommenter la constante MAX_CLOB_SIZE dans OracleFunctionCalling.php
Décommenter le bloc de validation dans la méthode largeCall()

Cela lèvera une HttpException (413 Payload Too Large) si un paramètre CLOB dépasse 50 MB.

Exemples de fonctions Oracle

Fonction simple

CREATE OR REPLACE FUNCTION MY_PACKAGE.MY_FUNCTION(
    p_param1 VARCHAR2,
    p_param2 NUMBER
) RETURN VARCHAR2 IS
BEGIN
    RETURN '{"data": {"result": "success", "id": ' || p_param2 || '}}';
END;

Fonction avec CLOB

CREATE OR REPLACE FUNCTION MY_PACKAGE.PROCESS_LARGE_DATA(
    p_user VARCHAR2,
    p_data CLOB
) RETURN VARCHAR2 IS
BEGIN
    -- Traiter le CLOB
    RETURN '{"data": {"processed": true}}';
END;

Fonction avec fichier

CREATE OR REPLACE FUNCTION MY_PACKAGE.SAVE_DOCUMENT(
    p_doc_id VARCHAR2,
    p_user VARCHAR2,
    p_filename VARCHAR2,
    p_file_size NUMBER,
    p_file_blob BLOB
) RETURN DATE IS
BEGIN
    INSERT INTO documents (doc_id, filename, file_data, created_at)
    VALUES (p_doc_id, p_filename, p_file_blob, SYSDATE);
    RETURN SYSDATE;
END;

Gestion des erreurs

Toutes les méthodes peuvent lever une HttpException en cas d'erreur :

use Symfony\Component\HttpKernel\Exception\HttpException;

try {
    $result = $this->oracleCaller->call('MY_FUNCTION', "'param'");
} catch (HttpException $e) {
    // Code HTTP 500 avec message descriptif
    logger->error($e->getMessage());
}

Exemples d'utilisation complets

Création d'un enregistrement

public function createUser(Request $request): Response
{
    $data = json_decode($request->getContent(), true);
    
    $params = sprintf(
        "'%s', '%s', %d",
        addslashes($data['name']),
        addslashes($data['email']),
        $data['age']
    );
    
    $result = $this->oracleCaller->call('USER_PACKAGE.CREATE_USER', $params);
    return $this->oracleCaller->handleResult($result, Response::HTTP_CREATED);
}

Upload de fichier

public function uploadDocument(Request $request): Response
{
    $data = json_decode($request->getContent(), true);
    
    $result = $this->oracleCaller->fileCall(
        'GED_PACKAGE.SAVE_DOCUMENT',
        "'{$data['documentId']}', '{$data['user']}', '{$data['filename']}'",
        $data['fileBase64'],
        ""
    );
    
    // Vérifier erreur de taille
    $decoded = json_decode($result);
    if (isset($decoded->error)) {
        return new Response($result, Response::HTTP_REQUEST_ENTITY_TOO_LARGE);
    }
    
    return $this->oracleCaller->handleResult($result, Response::HTTP_CREATED);
}

Traitement de données volumineuses

public function processBulkData(array $items): Response
{
    $largeJson = json_encode($items); // Peut dépasser 32000 caractères
    
    $result = $this->oracleCaller->largeCall(
        'DATA_PACKAGE.PROCESS_BULK',
        "'batch_001', 'import'",
        $largeJson,
        "'user@example.com'"
    );
    
    return $this->oracleCaller->handleResult($result, Response::HTTP_OK);
}

Hiérarchie de configuration

La taille maximale des fichiers est déterminée dans cet ordre (priorité décroissante) :

Valeur passée au constructeur
Variable d'environnement FILE_MAX_SIZE
Valeur par défaut (10MB)

Prérequis

PHP >= 8.0
Doctrine ORM >= 2.13 ou >= 3.0
Symfony HttpFoundation >= 5.4
Symfony HttpKernel >= 5.4
Base de données Oracle avec fonctions PL/SQL configurées

Sécurité

⚠️ Important : Cette bibliothèque construit des requêtes SQL dynamiques.

Les noms de fonctions doivent provenir de sources fiables
Les paramètres doivent être correctement échappés (utilisez addslashes())
Les fonctions Oracle doivent avoir les permissions appropriées
Ne passez jamais directement les entrées utilisateur sans validation

Licence

Propriétaire - Amsom Habitat

Auteur : Amsom Habitat

amsom-habitat / oracle-function-calling

Maintainers

Details