oci_bind_by_name

oci_bind_by_name(resource $statement, string $param, mixed $var, [int $max_length], [int $type]): bool
```php

Vincula una variable PHP `var` al marcador Oracle `param`. El hecho de vincular una variable es importante en términos de rendimiento de la base de datos Oracle, pero también en términos de seguridad relativa a las inyecciones SQL.

El vínculo permite a las bases de datos reutilizar el contexto de ejecución de la consulta así como el caché asociado, incluso cuando otro usuario o proceso la ejecuta. El vínculo reduce el riesgo de inyección SQL ya que los datos asociados a una variable vinculada nunca son tratados como parte de la consulta SQL. Por lo tanto, no es necesario añadir comillas ni escapar estos datos.

Las variables PHP vinculadas pueden cambiarse y la consulta re-ejecutarse sin necesidad de analizar de nuevo la consulta o de vincular de nuevo las variables.

Con Oracle, las variables vinculadas suelen dividirse en vínculo `IN` para los valores pasados a la base de datos, y en vínculo `OUT` para los valores a devolver a PHP. Una variable vinculada puede ser a la vez en vínculo `IN` y `OUT`. En este caso, el hecho de saber si la variable vinculada debe ser utilizada para la entrada o la salida será determinado en el momento de la ejecución.

Debe especificarse el parámetro `max_length` al utilizar el vínculo `OUT` para que PHP asigne suficiente memoria para contener el valor de retorno.

Para los vínculos `IN`, se recomienda definir el parámetro `max_length` si la consulta se ejecuta varias veces con valores diferentes para las variables PHP. De lo contrario, Oracle puede truncar los datos a la longitud del valor inicial de la variable PHP. Si no se conoce la longitud máxima necesaria, entonces llame de nuevo a la función `oci_bind_by_name` con los datos actuales, antes de cada llamada a la función `oci_execute`. El hecho de asociar una longitud superior a la necesaria tiene un impacto en la memoria asociada al proceso para la base de datos.

Una llamada a la funcionalidad de asociación de variables proporciona a Oracle la dirección de memoria a utilizar para leer los datos. Para los vínculos `IN`, esta dirección debe contener datos válidos al llamar a la función `oci_execute`. Esto significa que la variable vinculada debe permanecer en el contexto hasta la ejecución. Si no es así, pueden producirse resultados no esperados, así como errores de tipo "ORA-01460: unimplemented or unreasonable conversion requested". Para los vínculos `OUT`, un síntoma puede ser que no se haya definido ningún valor en la variable PHP.

Para una consulta que se ejecuta varias veces, los valores vinculados que nunca cambian pueden reducir la capacidad del optimizador de Oracle para elegir el mejor plan de ejecución. Para las consultas que tardan mucho tiempo, que rara vez se llaman varias veces, la asociación de variables no aporta ningún beneficio. Sin embargo, en los 2 casos, la asociación es más segura que colocar directamente las cadenas de caracteres en la consulta SQL, sabiendo que existe un riesgo de filtrado incorrecto de la entrada del usuario.

## Parámetros

`statement`  
Un identificador de consulta OCI8 válido.

`param`  
El marcador, prefijado por una coma, utilizado en la consulta. La coma es opcional en el parámetro `param`.

`var`  
La variable PHP a asociar con el marcador del parámetro `param`.

`max_length`  
Especifica la longitud máxima para los datos. Si el valor es -1, la función utilizará la longitud actual de los datos del parámetro `var` para definir la longitud máxima. En este caso, el parámetro `var` debe existir y contener datos al llamar a la función `oci_bind_by_name`.

`type`  
El tipo de datos a utilizar por Oracle para tratar los datos. Por omisión, vale `SQLT_CHR`. Oracle convertirá los datos entre este tipo y la columna de la base de datos (o las variables de tipo PL/SQL), cuando sea posible.

Si debe vincular tipos abstractos de datos (LOB/ROWID/BFILE), deberá asignarlos en primer lugar, con `oci_new_descriptor`. La longitud `length` no sirve para estos tipos y debería fijarse a -1.

Los valores posibles para el parámetro `type` son :

- `SQLT_FILE` o `OCI_B_BFILE` - para los BFILEs ;

- `SQLT_CFILE` o `OCI_B_CFILEE` - para los CFILEs ;

- `SQLT_CLOB` o `OCI_B_CLOB` - para los CLOBs ;

- `SQLT_BLOB` o `OCI_B_BLOB` - para los BLOBs ;

- `SQLT_RDD` o `OCI_B_ROWID` - para los ROWIDs ;

- `SQLT_NTY` o `OCI_B_NTY` - para los tipos de datos nombrados ;

- `SQLT_INT` o `OCI_B_INT` - para los enteros ;

- `SQLT_CHR` - para los VARCHAR ;

- `SQLT_BIN` o `OCI_B_BIN` - para las columnas RAW ;

- `SQLT_LNG` - para las columnas LONG ;

- `SQLT_LBI` - para las columnas LONG RAW ;

- `SQLT_RSET` - para los cursores creados con la función `oci_new_cursor`;

- `SQLT_BOL` o `OCI_B_BOL` - para los booleanos (requiere Oracle Database 12c)

## Valores devueltos

Esta función retorna `true` en caso de éxito o `false` si ocurre un error.

## Ejemplos

Inserción de datos con la función `oci_bind_by_name`

Una asociación con múltiples llamadas

Asociación con un bucle `foreach`

Asociación en una cláusula WHERE

Asociación con una cláusula LIKE

Asociación con REGEXP_LIKE

Para algunas condiciones utilizadas en las cláusulas IN, utilice variables vinculadas individuales. Los valores desconocidos en el momento de la ejecución podrán definirse a NULL. Esto permite utilizar una sola consulta para todos los usuarios de la aplicación, maximizando así la eficacia del caché Oracle DB.

Asociación de múltiples valores en una cláusula IN

Asociación de un ROWID devuelto por una consulta

Asociación de un ROWID en un INSERT

Asociación para una función almacenada PL/SQL

Asociación de parámetros a un procedimiento almacenado PL/SQL

Asociación sobre una columna CLOB

Asociación sobre un booleano en un script PL/SQL