Roles y capacidades de WordPress: Funciones de nota

Este es un tutorial perteneciente a una serie formada por cuatro partes que cubre el tema de los usuarios, los roles y las capacidades de WordPress. La serie cubrirá la arquitectura y el diseño de los roles de usuario en WordPress; destacará las funciones más importantes para interactuar con los usuarios y administrar los roles y las capacidades; y en el último tutorial, crearemos un ejemplo de la vida real que demuestra la utilidad de esta API.

Introducción

En la primera parte, solo cubrimos la teoría sobre los usuarios, los roles y las capacidades. Esta parte se centrará en el código y las funciones que WordPress ofrece para interactuar con este sistema. Obviamente, no vamos a cubrir todas las funciones que WordPress tiene, pero he intentado repasar las más importantes y útiles.

A medida que WordPress cambia y aparecen frecuentes actualizaciones, siempre debes volver a la documentación del Codex y comprobar si ha habido algún cambio. Proporcionaré un enlace a la página del Codex para cada función que cubramos aquí para tu conveniencia.

Gestión de usuarios

Los usuarios de WordPress son diferentes de los visitantes. Son personas que han registrado una cuenta con un nombre de usuario único en tu sitio. Puedes habilitar el registro de nuevos usuarios en tu sitio desde el panel Ajustes -> Generales marcando la casilla de verificación "Miembros -> Cualquiera puede registrarse".

En esta sección, cubriremos algunas de las útiles funciones para interactuar con los usuarios registrados en WordPress. Tu nueva configuración de WordPress debería tener al menos un usuario: el que configuró la instalación de WordPress. En versiones anteriores, este era el "administrador"; sin embargo, ahora puedes elegir un nombre de usuario al instalar WordPress.

1. Creación, actualización y eliminación de usuarios

   WordPress tiene una interfaz visual para crear, actualizar y eliminar usuarios. Deberías usarlo la mayor parte del tiempo. Sin embargo, hay casos en los que deseas hacerlo con programación: por ejemplo, al importar usuarios desde otro framework o si estás creando tu propio formulario de registro personalizado.

   WordPress tiene cuatro funciones para realizar estas actividades:

   • wp_create_user
   • wp_insert_user
   • wp_update_user
   • wp_delete_user

   Al principio, puede resultar un poco confuso. Todas las primeras 3 funciones pueden crear nuevos usuarios, y tanto "wp_insert_user" como "wp_update_user" pueden actualizar los usuarios existentes. Pero hay una razón para eso.

   Hay dos maneras de crear un nuevo usuario:

   1. Pasando únicamente la información mínima necesaria para crear el usuario (nombre de usuario, contraseña y correo electrónico). En este caso, debes utilizar la función wp_create_user.
   2. Pasando una matriz de datos del usuario. En este caso, debes utilizar la función wp_insert_user. Esto proporciona la capacidad de establecer los datos de usuario para tu usuario antes de añadirlo.

   Para actualizar un usuario existente, debes usar wp_update_user. Es posible usar el mismo wp_insert_user; sin embargo, esta función no hace "hash" a la contraseña de usuario y por lo tanto podría fallar. De manera que es mejor usar la función correcta para el trabajo correcto.

   A continuación, estoy esbozando un fragmento de uso de muestra para cada función. No obstante, si estás buscando documentación más detallada debes consultar el Códice.

   Uso de wp_create_user

   1	add_action( 'init', 'wpttuts_createuser' );
   2
   3	function wpttuts_createuser() {
   4	// User Data
   5	$user_name = 'new_user';
   6	$user_password = 'new_user_password';
   7	$user_email = 'new_user@gmail.com';
   8
   9	// Create the user
   10	$user_id = wp_create_user( $user_name, $user_password, $user_email );
   11
   12	// Checks if the function returned a WP Error Object
   13	if ( is_wp_error ($user_id) ) {
   14	$user_id->get_error_message();
   15	}
   16	else {
   17	// user created successfully
   18	}
   19	}

   Uso de wp_insert_user

   1	add_action( 'init', 'wpttuts_insertuser' );
   2
   3	function wpttuts_insertuser() {
   4	// Prepare the user data
   5	$user_data = array (
   6	'user_login' => 'new_user',
   7	'user_password' => 'new_user_password'
   8	'user_email' => 'new_user@gmail.com',
   9	'role' => 'administrator'
   10	);
   11
   12	// Create the user
   13	$user_id = wp_insert_user( $user_data );
   14
   15	// Checks if the function returned a WP Error Object
   16	if ( is_wp_error( $user_id ) ) {
   17	$user_id->get_error_message();
   18	}
   19	else {
   20	// user created successfully
   21	}
   22	}

   Uso de wp_update_user

   1	add_action( 'init', 'wpttuts_updateuser' );
   2
   3	function wpttuts_updateuser() {
   4
   5	// Prepare the user data
   6	$user_data = array (
   7	'user_id' => 3,
   8	'description' => ' Our newly created user'
   9	);
   10
   11	// Updates the user description
   12	$user_id = wp_update_user( $user_data );
   13
   14	// Checks if the function returned a WP Error Object
   15	if ( is_wp_error( $user_id ) ) {
   16	$user_id->get_error_message();
   17	}
   18	else {
   19	// user updated successfully
   20	}
   21	}

   Uso de wp_delete_user

   1	add_action( 'init', 'wpttuts_deleteuser' );
   2
   3	function wpttuts_deleteuser() {
   4	if ( wp_delete_user( 3, 1 ) ) {
   5	// User removed successfully
   6	}
   7	}

2. Obtener la lista de usuarios

   WordPress solía ofrecer dos funciones para recuperar la lista de usuarios, de modo que no tenías que consultar la base de datos. La primera función "get_users_of_blog()" devuelve una matriz con todos los usuarios del blog actual (o puedes pasar el ID de un blog si estás administrando una instalación multisitio). La segunda función "get_users()" devuelve una lista de usuarios en función de los argumentos que pases a la función. Esto elimina la necesidad de realizar consultas SQL personalizadas a la base de datos.

   Ambas funciones devuelven una matriz de objetos de datos de usuario. (Excepto para get_users() en donde puedes especificar la devolución de un único campo concreto.) El objeto de usuario se tratará con más detalles en la siguiente sección.

   La función "get_users_of_blog()" ahora está en desuso, por lo que ya no debería usarla y usar "get_users()" en su lugar. A continuación se muestra un ejemplo de uso de "get_users()".

   1	add_action( 'init', 'wpttuts_getusers' );
   2
   3	function wpttuts_getusers() {
   4	// Query criteria
   5	$args = array (
   6	'orderby' => 'url',
   7	'order' => 'ASC'
   8	);
   9
   10	// Get the users array
   11	$users = get_users( $args );
   12
   13	// Loop through users, and display their home page
   14	foreach( $users as $user) {
   15	echo '<a href="' . $user->user_url . '">' . $user->user_url . '</a>';
   16	}
   17	}

   El argumento de la función acepta más opciones. Puedes encontrar la lista completa de estas opciones en la página del Codex de la función.

   • blog_id Solo útil para instalaciones multisitio. El valor predeterminado es el ID de blog actual.
   • role Limita los usuarios devueltos al rol especificado.
   • include Una matriz de IDs de usuario para incluir en la consulta devuelta.
   • exclude una matriz de IDs de usuario para excluir de la consulta devuelta.

3. La clase WP_User

   La clase WP_User permite acceder a propiedades, capacidades y métodos relativos para un usuario determinado. Para crear una nueva instancia de la clase necesitas el ID del usuario o el nombre de usuario; y si estás en una instalación multisitio, también necesitarás el ID de blog.

   Puedes iniciar la clase para un usuario determinado y volcar el contenido de la clase. Esto mostrará solo las propiedades, pero sigue siendo útil si deseas leer dentro de la clase de usuario.

   1	add_action( 'init', 'wptuts_wpuserclass' );
   2
   3	function wptuts_wpuserclass() {
   4	$user = new WP_User( 1 );
   5	var_dump( $user );
   6	}

   A continuación se muestra un resumen de las propiedades y métodos de la clase WP_User:

   Propiedades de WP_User

   • data (Objeto con los detalles del usuario como el nombre de usuario, contraseña, URL...)
   • ID (Entero El ID de usuario)
   • caps (Matriz)
   • roles (Matriz roles asignados al usuario)
   • cap_key (Cadena)
   • allcaps (Matriz Todas las capacidades que tiene el usuario)
   • filter (Nulo)

   Métodos públicos de WP_User

   • get_role_caps() Establece las propiedades de los roles y las capacidades (allcaps).
   • add_role() Añade un rol al usuario.
   • remove_role() Elimina un rol del usuario.
   • set_role() Establezce un rol para el usuario. Esto eliminará los roles asignados anteriormente.
   • add_cap() Añade una capacidad al usuario.
   • remove_cap() Elimina la capacidad del usuario.
   • remove_all_caps() Elimina todas las capacidades del usuario.
   • has_cap() Comprueba si el usuario tiene una capacidad o un nombre de rol.

4. Metadatos de los usuarios

   Como se señaló en el artículo anterior, los metadatos de los usuarios son datos sobre el usuario guardados en la tabla wp_usermeta. Se guarda como valores clave/par, y el valor meta puede ser cualquier tipo de datos. El par no es necesariamente único. Puedes almacenar varios pares con la misma clave.

   Adición de metadatos de usuario

   La función add_user_meta() agrega nuevos metadatos de usuario. La función devuelve true cuando los datos se añaden correctamente y false si se produce un error. Como se mencionó anteriormente, es posible añadir múltiples valores meta con la misma clave. Si deseas que las clave meta sean únicas, establece el cuarto argumento en true.

   1	add_action('init', 'wptuts_addusermeta');
   2
   3	function wptuts_addusermeta() {
   4	// Add multiple meta values with the same meta key
   5	add_user_meta( 1, 'bookmarks', 'http://site1.com', false );
   6	add_user_meta( 1, 'bookmarks', 'http://site2.com', false );
   7	add_user_meta( 1, 'bookmarks', 'http://site3.com', false );
   8	}

   Recuperación de metadatos de usuario

   La función get_user_meta() devuelve el valor meta en función del ID de usuario y la clave meta clave que se le pasen.

   1	add_action('init', 'wptuts_getusermeta');
   2
   3	function wptuts_getusermeta() {
   4	// Retrieves the user bookmarks
   5	$bookmarks = get_user_meta( 1, 'bookmarks', false );
   6	echo '<ul>';
   7	foreach ( $bookmarks as $bookmark ) {
   8	echo '<li><a href="' . $bookmark . '">' . $bookmark . '</a></li>';
   9	}
   10	echo '</ul>';
   11	}

   Actualización de metadatos de un usuario

   La función update_user_meta() actualiza un único valor meta. Si hay varios valores para la misma clave meta y no se especificó ningún valor meta anterior, el nuevo valor sobrescribirá todos los valores meta anteriores.

   1	add_action('init', 'wptuts_updateusermeta');
   2
   3	function wptuts_updateusermeta() {
   4	// Updates a user bookmark
   5	update_user_meta( 1, 'bookmarks', 'https://site2.com', 'http://site2.com' );
   6	}

   Eliminación de metadatos de un usuario

   La función delete_user_data() elimina una sola o todas las meta claves/pares para una clave meta determinada. Si deseas quitar un único valor, debes especificarlo en el tercer argumento.

   1	add_action('init', 'wptuts_removeusermeta');
   2
   3	function wptuts_removeusermeta() {
   4	// Updates a user bookmark
   5	delete_user_meta( 1, 'bookmarks', 'https://site2.com' );
   6	}

Gestión de roles y capacidades

1. Creación y eliminación de roles

   Los roles de WordPress son extensibles. Puedes agregar y eliminar roles. Añadir un rol es bastante simple, necesitas un nombre slug de rol, un nombre a mostrar para el rol; y las capacidades que tiene dicho rol.

   1	add_action( 'init', 'wptuts_addrole' );
   2
   3	function wptuts_addrole() {
   4	add_role( 'uploader', 'Uploader', array('upload_files') );
   5	add_role( 'link_manager', 'Link Manager', array('manage_links') );
   6	}

   Si compruebas la página de ajustes de un usuario (User->Pick Any User->Edit), encontrarás que están disponibles los roles recién añadidos. Se muestran con el nombre a mostrar que hayas introducido.

   

   Es importante mencionar que la creación de roles debe hacerse solo una vez. Así que si estás enlazando a la acción "init" como en el código anterior, estás recreando el rol cada vez que se activa el código. Esto no es algo bueno; en la práctica, deseas crearlo una única vez. A continuación, puedes enlazarlo al gancho de activación del plugin, y asegúrate de eliminarlo cuando el plugin esté desactivado.

   Eliminar roles también es bastante sencillo. Solo necesitas el nombre del slug.

   1	add_action( 'init', 'wptuts_removerole' );
   2
   3	function wptuts_removerole() {
   4	remove_role( 'uploader' );
   5	remove_role( 'link_manager' );
   6	}

2. Adición de capacidades a roles

   De forma similar a los usuarios, los roles tienen una clase especial: WP_Role. Sin embargo, la inicialización de esta clase requiere tanto el nombre del rol como también sus capacidades; lo cual no es tan útil.

   WordPress ofrece otra función get_role() que requiere solo el nombre del rol e inicializa la clase por ti.

   1	add_action('init', 'wptuts_getrole');
   2
   3	function wptuts_getrole() {
   4	$role = get_role('editor');
   5	var_dump($role);
   6	}

   El objeto devuelto tiene dos propiedades y tres métodos.

   Propiedades WP_Role

   • capabilities Una matriz de las capacidades que tiene el rol.
   • name El nombre del rol.

   Métodos de WP_Role

   • add_cap() Añade la capacidad al objeto role
   • has_cap() Verifica si el rol tiene la capacidad
   • remove_cap() Elimina la capacidad del rol

3. Comprobación de permisos

   Los roles y las capacidades están ahí, pero no hacen nada. Debes aplicarlos en tu plugin o tema comprobándolos antes de ejecutar código. Siempre debes comprobar si existen capacidades en lugar de roles. Un usuario con un rol de "editor" no garantiza que tenga las capacidades predeterminadas que WordPress asigna a este rol, ya que pueden ser modificadas por otro plugin o el propio propietario del blog.

   WordPress tiene 3 funciones para comprobar los permisos, las cuales son intercambiables hasta cierto punto.

   • current_user_can()
   • user_can()
   • author_can()

   current_user_can() comprueba si el usuario actual tiene la capacidad especificada. También acepta un post u objeto para comprobar si hay meta-capacidades.

   user_can() funciona de la misma manera, pero puedes especificar el ID de usuario. Sin embargo, no comprueba si hay meta-capacidades. Así que es un poco deficiente si deseas comprobar si hay una meta-capacidad para un usuario diferente al usuario actual. Para ello, puedes utilizar la función author_can() que comprueba si un autor de un post puede realizar una tarea específica basada en una capacidad y un identificador de post.

   1	// checks if the post author of the first post can publish the post
   2	if ( author_can( 1, 'publish_posts') ) {
   3	publish_post_function(); // publish the post
   4	}
   5	else {
   6	echo "You don't have the right to publish the post";
   7	}

Conclusión

En esta parte, traté de cubrir tantas de las funciones de WordPress como sea posible, y también explicar cuándo debes utilizar cada una. Ahora, deberías ser capaz de crear un plugin o tema que utilice el sistema de capacidad. En la siguiente parte, voy a mostrarte cómo construir un plugin que utilice este sistema.