Página 1 de 1

Algunas funciones de phpBB  Tema Solucionado

Publicado: 19 Oct 2014, 15:36
por towen

Estas son algunas de las funciones más importantes del core de phpBB, o por lo menos las que más comúnmente se utilizan en las modificaciones. Esta guía solo es una explicación sobre las funciones, para aprender bien lo que hace cada una lo mejor es revisar los códigos de phpBB. Aclarar que esta guía se realizó en su día para phpBB 3.0.x


Haz clic en alguna función de la lista para verla.

  1. request_var

  2. append_sid

  3. generate_board_url

  4. redirect

  5. meta_refresh

  6. add_form_key

  7. check_form_key

  8. build_hidden_fields

  9. confirm_box

  10. page_header

  11. page_footer

  12. trigger_error

  13. login_box

  14. user_get_id_name

  15. get_username_string

  16. add_log


request_var

Código: Seleccionar todo

function request_var($var_name, $default, $multibyte = false, $cookie = false)

Sirve para recoger las variables enviadas al script por los métodos POST, GET o mediante cookies. Debe usarse siempre esta función en lugar de acceder directamente a las variables mediante las superglobales. El único caso donde está permitido usar $_POST es para verificar si se envió un formulario. Ej:

Código: Seleccionar todo

$submit = (isset($_POST['submit'])) ? true : false;

Argumentos

Spoiler
Mostrar

$var_name (cadena)

El nombre de la variable pasada al script

$default (array/booleano/entero/real/cadena)

El valor por defecto que se le dará a la variable si no se ha pasado al script. Importante!! el tipo de esta variable es el que se le dará al resultado final, es decir: si este parámetro es un entero el resultado final será un entero, si es un array el resultado será un array...

$multibyte (booleano)

Opcional, por defecto falso. Usado para recibir cadenas que contengan caracteres no ACSII (tildes, caracteres latinos o de otras lenguas...)

$cookie (booleano)

Opcional, por defecto falso. Indica si la variable se envía mediante cookies.

Devuelve

Spoiler
Mostrar

El contenido de la variable de nombre $var_name convertida al tipo correcto.

⬆️ Subir ⬆️


append_sid

Código: Seleccionar todo

append_sid($url, $params = false, $is_amp = true, $session_id = false)

Añade el id de sesión a la URL para que al acceder a ella el usuario se mantenga identificado. Solo lo agrega en caso de que no pueda mandarse el id de sesión mediante cookies.

Argumentos

Spoiler
Mostrar

$url (cadena)

La URL a la cual se le agregará el SID (ID de sesión), puede tener parámetros
(http://url_de_prueba/elemento.php?a=1#elemento)

$params (cadena/array/booleano)

Opcional, por defecto false indicando que no se pasan más elementos a la URL. Contiene la query string que se le pasa a la URL, puede ser una cadena donde los elementos se separan mediante & o & (según el tercer parámetro); o un array asociativo donde el índice de cada elemento se iguala a su valor. Es decir, aa=123&bb=789 representa lo mismo que array('aa' => 123, 'bb' => 789);

$is_amp (booleano)

Opcional, por defecto true. Si es true la url usará la identidad html &, si es false usará solamente &

$session_id (cadena)

Opcional, por defecto false para utilizar el id de sesión actual. Se puede usar para añadir un SID distinto al que tiene la sesión actual.

Devuelve

Spoiler
Mostrar

La URL formateada con la query string y el SID incluido si es necesario.

⬆️ Subir ⬆️


generate_board_url

Código: Seleccionar todo

generate_board_url($without_script_path = false)

Genera la URL directa al foro.

Argumentos

Spoiler
Mostrar

$without_script_path (booleano)

Opcional, por defecto false. Si es true se excluye la ruta al script que se está ejecutando.

Devuelve

Spoiler
Mostrar

La URL del foro

⬆️ Subir ⬆️


redirect

Código: Seleccionar todo

redirect($url, $return = false, $disable_cd_check = false)

Redirige al usuario a otra página, también hace algunas comprobaciones, por ejemplo si el protocolo de la URL es distinto a http(s) o ftp(s) da un error informando que la URL es insegura.

Argumentos

Spoiler
Mostrar

$url (cadena)

La URL a la que se redireccionará.

$return (booleano)

Opcional, por defecto false. Si es true no redirecciona sino que devuelve la URL

$disable_cd_check (booleano)

Opcional, por defecto false. Si es false impide que se redireccionen a sitios en otro dominio.

Devuelve

Spoiler
Mostrar

La URL pasada como primer parámetro preparada si el segundo parámetro es true.

⬆️ Subir ⬆️


meta_refresh

Código: Seleccionar todo

meta_refresh($time, $url, $disable_cd_check = false)

Redirecciona al usuario en un determinado tiempo indicado por el primer parámetro a la URL del segundo parámetro.

Argumentos

Spoiler
Mostrar

$time (entero)

El tiempo en segundos dentro del cual se redireccionará.

$url (cadena)

La URL a la que se redireccionará.

$disable_cd_check (booleano)

Opcional, por defecto false. Si es false impide que se redireccionen a sitios en otro dominio.

Devuelve

Spoiler
Mostrar

La URL pasada como primer parámetro luego de haber sido devuelta por la función redirect

⬆️ Subir ⬆️


add_form_key

Código: Seleccionar todo

add_form_key($form_name)  

Agrega un token secreto a un formulario para comprobarlo cuando el usuario envíe el formulario. Se utiliza para analizarlo con la función check_form_key y comprobar que el formulario no ha expirado.

Argumentos

Spoiler
Mostrar

$form_name (cadena)

El nombre del formulario, debe coincidir con el usado en la función check_form_key de lo contrario siempre devolverá que el formulario es inválido.

Devuelve

Spoiler
Mostrar

No devuelve nada pero crea una variable para las plantillas llamada S_FORM_TOKEN que debe ser agregada en el formulario (entre las etiquetas <form></form>).

⬆️ Subir ⬆️


check_form_key

Código: Seleccionar todo

check_form_key($form_name, $timespan = false, $return_page = '', $trigger = false)

Analiza el token del formulario enviado para comprobar si es válido.

Argumentos

Spoiler
Mostrar

$form_name (cadena)

El nombre del formulario, debe coincidir con el usado en la función add_form_key de lo contrario siempre devolverá que el formulario es inválido.

$timespan (entero)

Opcional, por defecto false. El tiempo máximo (en segundos) que el formulario tiene validez, si es false se usa el valor por defecto de phpBB.

$return_page (cadena)

Opcional, por defecto una cadena vacía. La dirección que aparecerá luego del mensaje de error en caso de que el formulario sea inválido y el argumento $trigger sea true.

$trigger (booleano)

Opcional, por defecto false. Si es true en caso de que el formulario sea inválido se lanzará un error con trigger_error.

Devuelve

Spoiler
Mostrar

Devuelve true en caso de que el formulario sea válido y false en caso contrario.

⬆️ Subir ⬆️


build_hidden_fields

Código: Seleccionar todo

build_hidden_fields($field_ary, $specialchar = false, $stripslashes = false)

Crea campos ocultos desde un array para usar en formularios o con la función confirm_box.

Argumentos

Spoiler
Mostrar

$field_ary (array)

Un array asociativo con los valores para construir los campos ocultos.

$specialchar (booleano)

Opcional, por defecto false. Si es true se les pasará la función htmlspecialchars a las claves y valores del array. Debe utilizarse si contiene caracteres que puedan interferir con el código HTML de la página, por ejemplo las comillas dobles y los signos menor y mayor (" < >)

$stripslashes (cadena)

Opcional, por defecto false. Si es true se les pasará la función stripslashes a las claves y valores del array.

Devuelve

Spoiler
Mostrar

El código HTML de los campos creados.

⬆️ Subir ⬆️


confirm_box

Código: Seleccionar todo

confirm_box($check, $title = '', $hidden = '', $html_body = 'confirm_body.html', $u_action = '')

Muestra una caja de confirmación. Útil para confirmar operaciones delicadas.
El modo de uso es el siguiente: se llama la función con el primer parámetro en true para comprobar si se ha enviado una confirmación, si la función devuelve true (ya se aceptó la confirmación) se ejecutan las acciones, si devuelve false (significa que no se ha mostrado la caja de confirmación) se muestra.

Argumentos

Mostrar
Spoiler
Mostrar

$check (booleano)

Si es true se comprueba que si se envió la confirmación, si es false muestra la caja de confirmación.

$title (cadena)

Opcional, por defecto una cadena vacía. El nombre de la variable de idioma con el título y el mensaje que tendrán la caja de confirmación, el texto del mensaje tendrá añadido al final _CONFIRM (Ej: TITULO, TITULO_CONFIRM). Si el TITULO no se puede encontrar en las variables de idioma se usará uno por defecto, si TITULO_CONFIRM no se puede encontrar en las variables de idioma se usará ese mismo texto.
Normalmente se utiliza $user->lang['CONFIRM_OPERATION'].

$hidden (cadena)

Opcional, por defecto una cadena vacía. Los campos ocultos que se enviarán junto a la confirmación. Normalmente si este argumento tiene un valor es el resultado de la función build_hidden_fields. Debe contener todas las variables enviadas por el usuario para mantener el comportamiento original del script.

$html_body (cadena)

Opcional, por defecto confirm_body.html que es la plantilla estándar de la caja de confirmación. El nombre de otra plantilla para la caja de confirmación.

$u_action (cadena)

Opcional, por defecto una cadena vacía que indica que se usará la URL de la página donde se encuentra el usuario. Permite definir una URL personalizada para la propiedad action del formulario.

Devuelve

Spoiler
Mostrar

Solo devuelve valores utilizables si el primer parámetro es true. Devuelve true si se ha mostrado la caja de confirmación y se ha aceptado, false si no se ha mostrado aún.

Ejemplo

Código: Seleccionar todo

// se comprueba si se mostró la confirmación y se aceptó
if (confirm_box(true))
{
    // Aquí las acciones delicadas
}
else
// si no se mostró la confirmación se envía
{
    // se muestra la confirmación, con los campos ocultos para no perder información
    confirm_box(false, $user->lang['CONFIRM_OPERATION'], build_hidden_fields(array(
        'mode'        => $mode,
        'submit'    => true,
        'usernames'    => $data['usernames'],
        'add'        => $data['add']))
    );
}

⬆️ Subir ⬆️


page_header

Código: Seleccionar todo

page_header($page_title = '', $display_online_list = true, $item_id = 0, $item = 'forum')

Envía las cabeceras y el título y crea varias variables para las plantillas.

Argumentos

Spoiler
Mostrar

$page_title (cadena)

El título que se mostrará en el navegador.

$display_online_list (booleano)

Opcional, por defecto true. Indica si se muestra la lista de usuarios registrados.

$item_id (entero) e $item (cadena)

Estos dos parámetros no hay que usarlos.

Devuelve

Spoiler
Mostrar

No devuelve ningún valor. Pero crea la mayoría de las variables que son usadas en las plantillas.

⬆️ Subir ⬆️


page_footer

Código: Seleccionar todo

page_footer($run_cron = true)  

Termina con la ejecución del script, muestra la página, descarga la caché y cierra la conexión a la base de datos.

Argumentos

Spoiler
Mostrar

$run_cron (booleano)

Opcional, por defecto true. Indica si se ejecutarán las tareas del cron.

Devuelve

Spoiler
Mostrar

No devuelve ningún valor. Crea las variables del debug para las plantillas y el enlace al PCA.

⬆️ Subir ⬆️


trigger_error

Código: Seleccionar todo

trigger_error ($error_msg, $error_type = E_USER_NOTICE)  

Aunque es una función nativa de PHP la incluyo ya que es muy utilizada en phpBB. Termina con la ejecución del script y muestra un mensaje.

Argumentos

Spoiler
Mostrar

$error_msg (cadena)

El texto que será mostrado. Se pueden (o se deben) usar las variables de idioma de phpBB. Ej: trigger_error($user->lang['ERROR']); o solo escribiendo el índice trigger_error('ERROR');

$error_type (booleano)

Opcional, por defecto la constante de PHP E_USER_NOTICE.

  • E_USER_NOTICE: Usado para mostrar alguna información, por ejemplo que se ha enviado un mensaje.

  • E_USER_WARNING: Usado para mostrar alguna información, la diferencia con

  • E_USER_NOTICE es que en el PCA se muestra el mensaje con un fondo rojo en vez de verde.

  • E_USER_ERROR: Para errores graves, por ejemplo algún problema con la base de datos.

Devuelve

Spoiler
Mostrar

No devuelve ningún valor.

⬆️ Subir ⬆️


login_box

Código: Seleccionar todo

login_box($redirect = '', $l_explain = '', $l_success = '', $admin = false, $s_display = true)

Muestra una caja de logueo.
Los dos primeros parámetros son los que más se usan al llamar la función, aunque puede hacerse sin parámetros.

Argumentos

Spoiler
Mostrar

$redirect (cadena)

Opcional. Permite definir la URL del foro a la cual se va a redireccionar luego de identificarse. Si se deja en blanco redirecciona a la página que llamó a la función o al índice del foro.

$l_explain (cadena)

El motivo por el cual debe identificarse. Dejar vacío para usar el valor por defecto (recomendado)

$l_success (cadena)

Mensaje en caso de identificarse correctamente. Dejar vacío para usar el valor por defecto (recomendado)

$admin (booleano)

Opcional, por defecto false. Si es true la caja de identificación será para acceder al PCA.

$s_display (booleano)

Opcional, por defecto true. Determina si se muestran todas las opciones (true) o solo lo más básico (false)

Devuelve

Spoiler
Mostrar

No devuelve ningún valor.

⬆️ Subir ⬆️


user_get_id_name

Código: Seleccionar todo

user_get_id_name(&$user_id_ary, &$username_ary, $user_type = false)

Obtiene los nombres de usuario pasandole los user_id o viceversa.

Argumentos

Spoiler
Mostrar

$user_id_ary (array)

Un array pasado por referencia que contiene los user_id de los usuarios a buscar, si se deja vacío se usarán los nombres de usuario

$username_ary (array)

Un array pasado por referencia que contiene los nombre de usuario de los usuarios a buscar, si se deja vacío se usarán los user_id. Si ninguno de los arrays está vacío la función devolverá false.

$user_type (array)

Opcional, por defecto false. Un array con los user_type que se permitirán. Si se deja vacío no se tendrán restricciones con el user_type.

Devuelve

Spoiler
Mostrar

Devuelve false en caso de éxito o si los arrays de los dos primeros argumentos no están vacíos (solo uno puede estar ocupado). En caso de error devuelve la cadena del error.

Ejemplo

Código: Seleccionar todo

$user_id_ary = array(1, 2, 4, 6, 49, 243);
user_get_id_name($user_id_ary, $username_ary);
// $username_ary contiene ahora los nombres de usuario correspondientes a cada ID

$user_id_ary = array(2, 4, 6);
$username_ary = array('admin', 'test')
user_get_id_name($user_id_ary, $username_ary);
// la función returna false ya que no se pueden pasar los dos arrays con contenido

$user_id_ary = array(1, 2, 4, 6, 49, 243);
user_get_id_name($user_id_ary, $username_ary, array(0, 3));
// $username_ary contiene ahora los nombres de usuario correspondientes a cada ID pero solo si son usuarios normales o fundadores  

⬆️ Subir ⬆️


get_username_string

Código: Seleccionar todo

get_username_string($mode, $user_id, $username, $username_colour = '', $guest_username = false, $custom_profile_url = false)

Obtiene el nombre de usuario con distintas opciones según los parámetros que se le pasen a la función.

Argumentos

Spoiler
Mostrar

$mode (cadena)

Dependiendo del valor que se le pase la función devolverá:

  • profile: La URL al perfil.

  • username: El nombre de usuario.

  • colour: El color del usuario.

  • full: El código HTML de un enlace coloreado al perfil de usuario.

  • no_profile: Similar a full pero no devuelve un enlace.

$user_id (entero)

El id del usuario.

$username (cadena)

El nombre de usuario

$username_colour (cadena)

Opcional, por defecto una cadena vacía. El color del usuario.

$guest_username (cadena)

Opcional, por defecto false. Usado si el $user_id es 1 (usuario Anónimo) para el nombre de usuario del usuario Invitado.

$custom_profile_url (cadena)

Opcional, por defecto false. Una URL personalizada a la que al final se le agregará &u=$user_id y que será usada si el primer parámetro es igual a profile o full

Devuelve

Spoiler
Mostrar

Devuelve una cadena con lo solicitado con $mode

⬆️ Subir ⬆️


add_log

Código: Seleccionar todo

add_log()  

Agrega un registro (log).

Un pequeño truco:
Si deseas que alguna acción que normalmente crea un log (por ejemplo añadir un usuario a un grupo) no lo haga agrega la siguiente línea antes de esa acción: $GLOBALS['skip_add_log'] = true; Luego de que se ejecute esa acción agrega usa la siguiente línea para volver a activar los logs: unset($GLOBALS['skip_add_log']);

Argumentos

Spoiler
Mostrar

Acepta un número variable de argumentos. Por defecto el primero es el tipo de log que es, puede ser: admin, mod, user y critical.

  • Si el tipo de log es admin o critical el segundo argumento será la variable de idioma de la acción, y el resto de los parámetros serán usados como array junto a la acción en la función vsprintf para mostrar el log en el PCA o PCM.

  • Si el tipo de log es user el segundo argumento será el id del usuario al que se le ejecuta la acción (para agregarlo en sus notas, que son visibles desde el PCM), del tercer parámetro en adelante serán iguales a los de los de tipo admin.

  • Si el tipo de log es mod el segundo argumento será el id del foro donde se realiza la acción y el tercer parámetro será el id del tema. El resto de los parámetros serán iguales a los de los de tipo admin.

Devuelve

Spoiler
Mostrar

Devuelve el id del log agregado.

Ejemplo

Código: Seleccionar todo

// ejemplos de un log de tipo admin
add_log('admin', 'LOG_USER_WARNING', $user_row['username']);

// se añade el id del log a una variable para ser utilizada en otras operaciones
$log_id = add_log('user', $user_row['user_id'], 'LOG_USER_WARNING_BODY', $warning);
        
// si el log de moderador no está relacionado con un post se pueden dejar en cero los parámetros
add_log('mod', 0, 0, 'LOG_USER_FEEDBACK', $userrow['username']);

// el segundo parámetro sirve para asignar logs a usuarios, 
// así se puede buscar cada acción en la que se vio involucrado ese usuario
add_log('user', $user_id, 'LOG_USER_GENERAL', $usernote);

⬆️ Subir ⬆️