README

Bibliothèque PHP pour simplifier les appels aux fonctions et procédures Oracle via Doctrine, avec support avancé des CLOB, BLOB et compression automatique des PDFs.

Fonctionnalités

Appels simples de fonctions Oracle en une ligne
CLOB volumineux : découpage automatique en chunks de 32 KB
Fichiers base64 : conversion automatique vers BLOB Oracle
Compression PDF automatique vers une taille cible (via API Document)
Rollback automatique et exceptions structurées
Génération de réponse HTTP Symfony

Installation

composer require amsom-habitat/oracle-function-calling

Prérequis

PHP >= 8.1
Doctrine DBAL ^3.3 || ^4.0
Doctrine ORM ^3.0
Symfony HttpFoundation / HttpKernel ^6.4 || ^7.0 || ^8.0
Base de données Oracle avec fonctions PL/SQL configurées

Configuration

services.yaml

services:
    AmsomUtilities\OracleFunctionCalling:
        arguments:
            $managerRegistry: '@doctrine'
            $fileMaxSize: '%env(int:FILE_MAX_SIZE)%'
            $fileCompressSize: '%env(int:FILE_COMPRESS_SIZE)%'
            $apiDocumentUrl: '%env(API_DOCUMENT_URL)%'

Variables d'environnement

# Taille maximale des fichiers (10 MB par défaut)
FILE_MAX_SIZE=10485760

# Taille cible de compression PDF (1 MB par défaut)
FILE_COMPRESS_SIZE=1000000

# URL de l'API Document pour la compression PDF (optionnel)
API_DOCUMENT_URL=http://api_document

Configuration programmatique

$oracleCaller = new OracleFunctionCalling(
    $managerRegistry,
    fileMaxSize: 20971520,       // 20 MB max
    apiDocumentUrl: 'https://api-document.example.com'
);

// Ou avec chaînage
$oracleCaller
    ->setFileMaxSize(10 * 1024 * 1024)
    ->setApiDocumentUrl('https://api-document.example.com');

Hiérarchie de configuration (priorité décroissante)

Valeur passée au constructeur
Variable d'environnement (FILE_MAX_SIZE, FILE_COMPRESS_SIZE, API_DOCUMENT_URL)
Valeur par défaut (DEFAULT_FILE_MAX_SIZE = 10 MB, DEFAULT_FILE_COMPRESS_SIZE = 1 MB)

Utilisation

1. Appel simple

$result = $oracleCaller->call(
    'MY_PACKAGE.MY_FUNCTION',
    "'param1', 123, 'param2'"
);

echo $result; // {"data": {"id": 123, "status": "success"}}

Avec rollback automatique en cas d'erreur :

$result = $oracleCaller->call(
    'MY_PACKAGE.CREATE_USER',
    "'john.doe', 'john@example.com'",
    rollbackIfFail: true
);

2. Appel avec CLOB volumineux

Pour passer de grandes chaînes (JSON, XML, textes > 32 000 caractères) :

$largeData = json_encode($bigArray);

$result = $oracleCaller->largeCall(
    'MY_PACKAGE.PROCESS_DATA',
    "'user123', 'action'",  // Paramètres AVANT le CLOB
    $largeData,              // Le CLOB volumineux
    "'additionalParam'"      // Paramètres APRÈS (optionnel)
);

Les virgules de séparation et l'échappement des apostrophes sont gérés automatiquement.

3. Appel avec fichier (BLOB)

$base64File = base64_encode(file_get_contents('document.pdf'));

$result = $oracleCaller->fileCall(
    'MY_PACKAGE.SAVE_DOCUMENT',
    "'DOC123', 'john.doe', 'document.pdf'",
    $base64File
);

$decoded = json_decode($result);
if (isset($decoded->error)) {
    // Le fichier dépasse la limite autorisée
}

4. Génération de réponse HTTP

public function createAction(Request $request): Response
{
    $result = $this->oracleCaller->call(
        'MY_PACKAGE.CREATE_ITEM',
        "'param1', 'param2'"
    );

    // Retourne HTTP 201 si succès (JSON contient `data`), 400 sinon
    return $this->oracleCaller->handleResult($result, Response::HTTP_CREATED);
}

Convention Oracle :

// Succès — JSON avec propriété `data`
{"data": {"id": 123, "message": "Créé avec succès"}}

// Erreur — JSON sans `data`
{"error": "Message d'erreur", "code": "ERR_001"}

Compression automatique des PDFs

La compression s'active automatiquement pour les fichiers PDF dans fileCall() si API_DOCUMENT_URL est configurée.

Détection PDF

mimeType explicite : 'application/pdf'
Préfixe data URI : data:application/pdf;base64,...
Signature du fichier : header %PDF

Options

$result = $oracleCaller->fileCall(
    'SAVE_DOCUMENT',
    "'DOC123', 'contract.pdf'",
    $pdfBase64,
    "",
    [
        'mimeType'    => 'application/pdf',  // Force la détection PDF
        'compressPdf' => true,               // Active/désactive (défaut: true)
        'targetSize'  => 500000,             // Taille cible en octets (défaut: FILE_COMPRESS_SIZE)
    ]
);

Tailles cibles recommandées

Cas d'usage	Taille cible
Archives	200–500 KB
Documents courants	500 KB–1 MB
Documents importants	1–2 MB
Documents légaux	2–3 MB

Si la compression n'est pas bénéfique ou si l'API est indisponible, le fichier original est conservé silencieusement (log d'avertissement).

Gestion des erreurs

Methode	Erreur Oracle	Fichier trop grand
`call()`	`HttpException` (500)	N/A
`largeCall()`	`HttpException` (500)	N/A
`fileCall()`	`HttpException` (500)	JSON d'erreur (string)

use Symfony\Component\HttpKernel\Exception\HttpException;

try {
    $result = $oracleCaller->call('MY_FUNCTION', "'param'");
} catch (HttpException $e) {
    // $e->getStatusCode() => 500
    // $e->getMessage() => Message d'erreur Oracle
}

Constantes disponibles

OracleFunctionCalling::CLOB_CHUNK_SIZE         // 32 000 caractères
OracleFunctionCalling::RESPONSE_SIZE           // 4 000 caractères (max réponse Oracle VARCHAR2)
OracleFunctionCalling::DEFAULT_FILE_MAX_SIZE   // 10 485 760 octets (10 MB)
OracleFunctionCalling::DEFAULT_FILE_COMPRESS_SIZE // 1 000 000 octets (1 MB)

Recommandations PHP

memory_limit = 256M
max_execution_time = 60
post_max_size = 20M
upload_max_filesize = 20M

Sécurité

Cette bibliothèque construit des blocs PL/SQL dynamiques.

Les noms de fonctions ($function) doivent provenir de sources fiables (jamais de l'input utilisateur direct)
Tous les paramètres sont de la responsabilité de l'appelant : $params, $paramsBeforeLarge, $paramsAfterLarge, $largeParam doivent être échappés avant appel (apostrophes → '')
Le contenu base64 passé à fileCall() est safe par nature (alphabet base64)

Exemples d'appels Oracle

Fonction simple

CREATE OR REPLACE FUNCTION MY_PACKAGE.CREATE_USER(
    p_name  VARCHAR2,
    p_email VARCHAR2
) RETURN VARCHAR2 IS
    v_id NUMBER;
BEGIN
    INSERT INTO users (name, email) VALUES (p_name, p_email) RETURNING id INTO v_id;
    COMMIT;
    RETURN '{"data": {"id": ' || v_id || '}}';
EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        RETURN '{"error": "' || SQLERRM || '"}';
END;

Fonction avec CLOB

CREATE OR REPLACE FUNCTION MY_PACKAGE.PROCESS_BULK_DATA(
    p_user_id  VARCHAR2,
    p_json_data CLOB
) RETURN VARCHAR2 IS
BEGIN
    -- traitement ...
    COMMIT;
    RETURN '{"data": {"status": "ok"}}';
EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        RETURN '{"error": "' || SQLERRM || '"}';
END;

Fonction avec fichier (BLOB)

CREATE OR REPLACE FUNCTION DOC_PACKAGE.SAVE_DOCUMENT(
    p_title     VARCHAR2,
    p_file_size NUMBER,
    p_file_blob BLOB
) RETURN VARCHAR2 IS
    v_id VARCHAR2(50);
BEGIN
    v_id := SYS_GUID();
    INSERT INTO documents (id, title, file_data, file_size)
    VALUES (v_id, p_title, p_file_blob, p_file_size);
    COMMIT;
    RETURN '{"data": {"documentId": "' || v_id || '"}}';
EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        RETURN '{"error": "' || SQLERRM || '"}';
END;

Support

Consulter les logs de l'application (grep "OracleFunctionCalling")
Vérifier la configuration Symfony et les variables d'environnement
Tester les fonctions Oracle directement via SQL Developer

Licence

Propriétaire — AMSOM Habitat

Changelog

v3.0.0

Compatibilité Doctrine DBAL ^3.3 || ^4.0 et ORM ^3.0
Utilisation de Connection::getNativeConnection() pour les paramètres OUTPUT Oracle (contournement de la suppression de PDO::PARAM_INPUT_OUTPUT dans DBAL 4)
Typage complet de toutes les signatures publiques
PHP >= 8.1 requis

v2.0.0

Ajout de la compression automatique des PDFs par taille cible
Support du paramètre options dans fileCall
Détection automatique des PDFs (3 méthodes)

v1.x.x

Gestion des CLOB et BLOB
Appels simples de fonctions Oracle
Support Symfony

amsom-habitat/oracle-function-calling

包简介

关键字：

README 文档