README

Lib PHP pour appeler facilement des fonctions/procédures Oracle avec Doctrine.

Installation

composer require amsom-habitat/oracle-function-calling

Points clés

Appel simple de fonction Oracle
Support CLOB volumineux (découpage automatique)
Envoi de fichiers base64 (BLOB)
Limite de taille configurable
Réponse HTTP Symfony prête à l'emploi

Configuration rapide

Symfony

services:
    AmsomUtilities\OracleFunctionCalling: ~
    # ou avec options
    AmsomUtilities\OracleFunctionCalling:
        arguments:
            $managerRegistry: '@doctrine'
            $fileMaxSize: 10485760 # 10MB par défaut

Variable d'environnement

FILE_MAX_SIZE=10485760

Exemples d'utilisation

Appel simple

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

Appel avec CLOB volumineux

$result = $oracleCaller->largeCall('MY_FUNCTION', "'param1'", $grosTexte, "'param2'");

Appel avec fichier base64

$result = $oracleCaller->fileCall('MY_FUNCTION', "'param1'", $fichierBase64);

Générer une réponse HTTP Symfony

return $oracleCaller->handleResult($result, 201);

    // $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 :

1. Décommenter la constante `MAX_CLOB_SIZE` dans `OracleFunctionCalling.php`
2. 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) :

1. **Valeur passée au constructeur**
2. **Variable d'environnement** `FILE_MAX_SIZE`
3. **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

Package info

Statistics

Security

README

Installation

Points clés

Configuration rapide

Exemples d'utilisation

Appel simple

Appel avec CLOB volumineux

Appel avec fichier base64

Générer une réponse HTTP Symfony