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)

1. Valeur passée au constructeur
2. Variable d'environnement (FILE_MAX_SIZE, FILE_COMPRESS_SIZE, API_DOCUMENT_URL)
3. 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

1. mimeType explicite : 'application/pdf'
2. Préfixe data URI : data:application/pdf;base64,...
3. 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

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

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

1. Consulter les logs de l'application (grep "OracleFunctionCalling")
2. Vérifier la configuration Symfony et les variables d'environnement
3. 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