Cómo crear un plugin de administración de avatares de WordPress: Toques finales

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

Avatar Manager para WordPress es un plugin sencillo y agradable que almacena fácilmente avatares de forma local y mucho más.

Mejora tu sitio web de WordPress permitiendo que tus usuarios elijan entre usar Gravatar o una imagen de avatar autoalojada directamente desde la pantalla Tu perfil. Flujo de trabajo mejorado, generación de imágenes a petición y permisos de usuario personalizados en una interfaz nativa. Dá la bienvenida al plugin Avatar Manager.

Una rápida recapitulación

En la primera parte de nuestro tutorial, revisamos lo siguiente:

qué es un plugin de WordPress;
cómo crear un plugin básico de WordPress, y cómo elegir una licencia y un formato apropiados para el número de versión;
qué son los ganchos de acción y filtro y cómo usarlos para crear nuestro plugin;
cómo añadir nuevos ajustes a las pantallas de configuración existentes;
cómo hacer que un plugin sea más flexible mediante el uso de opciones personalizadas.

Hoy, llevaremos las cosas más allá y terminaremos nuestro plugin: gestionaremos las cargas de avatares y la generación de imágenes bajo demanda, internacionalizaremos nuestro plugin y mucho más.

Paso 1. Cambiar el tamaño de una imagen de avatar

Comencemos escribiendo la siguiente función:

/**
 * Generates a resized copy of the specified avatar image.
 *
 * @uses wp_upload_dir() For retrieving path information on the currently
 * configured uploads directory.
 * @uses wp_basename() For i18n friendly version of basename().
 * @uses wp_get_image_editor() For retrieving a WP_Image_Editor instance and
 * loading a file into it.
 * @uses is_wp_error() For checking whether the passed variable is a WordPress
 * Error.
 * @uses do_action() For calling the functions added to an action hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param string $url URL of the avatar image to resize.
 * @param int $size Size of the new avatar image.
 * @return array Array with the URL of the new avatar image.
 */
function avatar_manager_avatar_resize( $url, $size ) {
	// Retrieves path information on the currently configured uploads directory.
	$upload_dir = wp_upload_dir();

	$filename  = str_replace( $upload_dir['baseurl'], $upload_dir['basedir'], $url );
	$pathinfo  = pathinfo( $filename );
	$dirname   = $pathinfo['dirname'];
	$extension = $pathinfo['extension'];

	// i18n friendly version of basename().
	$basename = wp_basename( $filename, '.' . $extension );

	$suffix    = $size . 'x' . $size;
	$dest_path = $dirname . '/' . $basename . '-' . $suffix . '.' . $extension;
	$avatar    = array();

	if ( file_exists( $dest_path ) ) {
		$avatar['url']  = str_replace( $upload_dir['basedir'], $upload_dir['baseurl'], $dest_path );
		$avatar['skip'] = true;
	} else {
		// Retrieves a WP_Image_Editor instance and loads a file into it.
		$image = wp_get_image_editor( $filename );

		if ( ! is_wp_error( $image ) ) {
			// Resizes current image.
			$image->resize( $size, $size, true );

			// Saves current image to file.
			$image->save( $dest_path );

			$avatar['url']  = str_replace( $upload_dir['basedir'], $upload_dir['baseurl'], $dest_path );
			$avatar['skip'] = false;
		}
	}

	// Calls the functions added to avatar_manager_avatar_resize action hook.
	do_action( 'avatar_manager_avatar_resize', $url, $size );

	return $avatar;
}

Resumen

La función avatar_manager_avatar_resize() genera una copia redimensionada de la imagen de avatar especificada.
La llamada wp_upload_dir() devuelve una matriz que contiene información sobre la ruta de acceso en el directorio de cargas actualmente configurado.
La función str_replace() sustituye todas las instancias de la cadena de búsqueda por la cadena de reemplazo.
La función pathinfo() devuelve información sobre una ruta de acceso al archivo.
La función wp_basename() es la versión i18n amigable de basename() que devuelve el componente final del nombre de una ruta de acceso.
La función file_exists() comprueba si existe un archivo o directorio.
El indicador skip se establece en true si el archivo de imagen de destino ya existe, de lo contrario se genera una nueva imagen.
La función wp_get_image_editor() devuelve una instancia WP_Image_Editor y carga un archivo en ella. Con eso podemos manipular la imagen llamando a métodos en ella.
La función is_wp_error() comprueba si la variable pasada es un error de WordPress.
Luego, cambiamos el tamaño y guardamos la imagen llamando a los métodos resize() y save() del objeto $image.
do_action() ejecuta un gancho creado por add_action(); esto permite que los temas y plugins se conecten a la acción avatar_manager_avatar_resize que se activa después de cambiar el tamaño de una imagen de avatar.

Paso 2. Eliminar una imagen de avatar

Antes de encargarnos de las actualizaciones de perfil, tenemos que definir una función más:

/**
 * Deletes an avatar image based on attachment ID.
 *
 * @uses get_post_meta() For retrieving attachment meta fields.
 * @uses wp_upload_dir() For retrieving path information on the currently
 * configured uploads directory.
 * @uses delete_post_meta() For deleting attachment meta fields.
 * @uses get_users() For retrieving an array of users.
 * @uses delete_user_meta() For deleting user meta fields.
 * @uses do_action() For calling the functions added to an action hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param int $attachment_id An attachment ID
 */
function avatar_manager_delete_avatar( $attachment_id ) {
	// Retrieves attachment meta field based on attachment ID.
	$is_custom_avatar = get_post_meta( $attachment_id, '_avatar_manager_is_custom_avatar', true );

	if ( ! $is_custom_avatar )
		return;

	// Retrieves path information on the currently configured uploads directory.
	$upload_dir = wp_upload_dir();

	// Retrieves attachment meta field based on attachment ID.
	$custom_avatar = get_post_meta( $attachment_id, '_avatar_manager_custom_avatar', true );

	if ( is_array( $custom_avatar ) ) {
		foreach ( $custom_avatar as $file ) {
			if ( ! $file['skip'] ) {
				$file = str_replace( $upload_dir['baseurl'], $upload_dir['basedir'], $file['url'] );
				@unlink( $file );
			}
		}
	}

	// Deletes attachment meta fields based on attachment ID.
	delete_post_meta( $attachment_id, '_avatar_manager_custom_avatar' );
	delete_post_meta( $attachment_id, '_avatar_manager_custom_avatar_rating' );
	delete_post_meta( $attachment_id, '_avatar_manager_is_custom_avatar' );

	// An associative array with criteria to match.
	$args = array(
		'meta_key'   => 'avatar_manager_custom_avatar',
		'meta_value' => $attachment_id
	);

	// Retrieves an array of users matching the criteria given in $args.
	$users = get_users( $args );

	foreach ( $users as $user ) {
		// Deletes user meta fields based on user ID.
		delete_user_meta( $user->ID, 'avatar_manager_avatar_type' );
		delete_user_meta( $user->ID, 'avatar_manager_custom_avatar' );
	}

	// Calls the functions added to avatar_manager_delete_avatar action hook.
	do_action( 'avatar_manager_delete_avatar', $attachment_id );
}

add_action( 'delete_attachment', 'avatar_manager_delete_avatar' );

Resumen

Se invoca al enlace de acción delete_attachment cuando wp_delete_attachment() elimina un archivo adjunto.
get_post_meta() devuelve los valores de los campos personalizados con la clave especificada de la entrada especificado. En primer lugar, comprobamos si el archivo adjunto con el ID especificado es una imagen de avatar.
La llamada is_array() descubre si una variable es una matriz.
A continuación, usamos la función unlink() para eliminar la imagen del avatar, incluidas sus copias redimensionadas, pero omitiendo aquellas con la marca skip establecida en true.
La función delete_post_meta() elimina todos los campos personalizados con la clave especificada de la entrada especificada.
La función get_users() recupera una matriz de usuarios que coinciden con los criterios indicados en $args.
La función delete_user_meta() elimina los criterios de coincidencia de metadatos de un usuario.
Por último, ejecutamos el gancho de acción avatar_manager_delete_avatar.

Paso 3. Actualizar un perfil de usuario

Al actualizar un perfil de usuario, no solo necesitamos guardar las opciones modificadas por el usuario, sino también gestionar las cargas y las eliminaciones de avatares. Hagámoslo:

/**
 * Updates user profile based on user ID.
 *
 * @uses avatar_manager_get_options() For retrieving plugin options.
 * @uses sanitize_text_field() For sanitizing a string from user input or from
 * the database.
 * @uses update_user_meta() For updating user meta fields.
 * @uses get_user_meta() For retrieving user meta fields.
 * @uses update_post_meta() For updating attachment meta fields.
 * @uses wp_handle_upload() For handling PHP uploads in WordPress.
 * @uses wp_die() For killing WordPress execution and displaying HTML error
 * message.
 * @uses __() For retrieving the translated string from the translate().
 * @uses avatar_manager_delete_avatar() For deleting an avatar image.
 * @uses wp_insert_attachment() For inserting an attachment into the media
 * library.
 * @uses wp_generate_attachment_metadata() For generating metadata for an
 * attachment.
 * @uses wp_update_attachment_metadata() For updating metadata for an
 * attachment.
 * @uses avatar_manager_avatar_resize() For generating a resized copy of the
 * specified avatar image.
 * @uses avatar_manager_delete_avatar() For deleting an avatar image based on
 * attachment ID.
 * @uses get_edit_user_link() For getting the link to the users edit profile
 * page in the WordPress admin.
 * @uses add_query_arg() For retrieving a modified URL (with) query string.
 * @uses wp_redirect() For redirecting the user to a specified absolute URI.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param int $user_id User to update.
 */
function avatar_manager_edit_user_profile_update( $user_id ) {
	// Retrieves plugin options.
	$options = avatar_manager_get_options();

	// Sanitizes the string from user input.
	$avatar_type = isset( $_POST['avatar_manager_avatar_type'] ) ? sanitize_text_field( $_POST['avatar_manager_avatar_type'] ) : 'gravatar';

	// Updates user meta field based on user ID.
	update_user_meta( $user_id, 'avatar_manager_avatar_type', $avatar_type );

	// Retrieves user meta field based on user ID.
	$custom_avatar = get_user_meta( $user_id, 'avatar_manager_custom_avatar', true );

	if ( ! empty( $custom_avatar ) ) {
		// Sanitizes the string from user input.
		$custom_avatar_rating = isset( $_POST['avatar_manager_custom_avatar_rating'] ) ? sanitize_text_field( $_POST['avatar_manager_custom_avatar_rating'] ) : 'G';

		// Updates attachment meta field based on attachment ID.
		update_post_meta( $custom_avatar, '_avatar_manager_custom_avatar_rating', $custom_avatar_rating );
	}

	...
}

add_action( 'edit_user_profile_update', 'avatar_manager_edit_user_profile_update' );
add_action( 'personal_options_update', 'avatar_manager_edit_user_profile_update' );

Resumen

Las acciones edit_user_profile_update y personal_options_update se utilizan generalmente para guardar campos personalizados que se han añadido a la página de perfil de WordPress.
La función sanitize_text_field() desinfecta una cadena a partir de la entrada del usuario o de la base de datos.
La función update_user_meta() actualiza el campo meta del usuario en función del ID de usuario, mientras que get_user_meta() recupera un único campo meta o todos los campos de metadatos del usuario para un usuario dado.
La función update_post_meta() actualiza el valor de una clave meta existente (campo personalizado) para la entrada especificada.

Gestionar las cargas de avatares

Para controlar las cargas de avatares, escribe el siguiente código:

if ( isset( $_POST['avatar-manager-upload-avatar'] ) && $_POST['avatar-manager-upload-avatar'] ) {
	if ( ! function_exists( 'wp_handle_upload' ) )
		require_once( ABSPATH . 'wp-admin/includes/file.php' );

	// An associative array with allowed MIME types.
	$mimes = array(
		'bmp'  => 'image/bmp',
		'gif'  => 'image/gif',
		'jpe'  => 'image/jpeg',
		'jpeg' => 'image/jpeg',
		'jpg'  => 'image/jpeg',
		'png'  => 'image/png',
		'tif'  => 'image/tiff',
		'tiff' => 'image/tiff'
	);

	// An associative array to override default variables.
	$overrides = array(
		'mimes'     => $mimes,
		'test_form' => false
	);

	// Handles PHP uploads in WordPress.
	$avatar = wp_handle_upload( $_FILES['avatar_manager_import'], $overrides );

	if ( isset( $avatar['error'] ) )
		// Kills WordPress execution and displays HTML error message.
		wp_die( $avatar['error'],  __( 'Image Upload Error', 'avatar-manager' ) );

	if ( ! empty( $custom_avatar ) )
		// Deletes users old avatar image.
		avatar_manager_delete_avatar( $custom_avatar );

	// An associative array about the attachment.
	$attachment = array(
		'guid'           => $avatar['url'],
		'post_content'   => $avatar['url'],
		'post_mime_type' => $avatar['type'],
		'post_title'     => basename( $avatar['file'] )
	);

	// Inserts the attachment into the media library.
	$attachment_id = wp_insert_attachment( $attachment, $avatar['file'] );

	// Generates metadata for the attachment.
	$attachment_metadata = wp_generate_attachment_metadata( $attachment_id, $avatar['file'] );

	// Updates metadata for the attachment.
	wp_update_attachment_metadata( $attachment_id, $attachment_metadata );

	$custom_avatar = array();

	// Generates a resized copy of the avatar image.
	$custom_avatar[ $options['default_size'] ] = avatar_manager_avatar_resize( $avatar['url'], $options['default_size'] );

	// Updates attachment meta fields based on attachment ID.
	update_post_meta( $attachment_id, '_avatar_manager_custom_avatar', $custom_avatar );
	update_post_meta( $attachment_id, '_avatar_manager_custom_avatar_rating', 'G' );
	update_post_meta( $attachment_id, '_avatar_manager_is_custom_avatar', true );

	// Updates user meta fields based on user ID.
	update_user_meta( $user_id, 'avatar_manager_avatar_type', 'custom' );
	update_user_meta( $user_id, 'avatar_manager_custom_avatar', $attachment_id );
}

Resumen

function_exists() devuelve true si se ha definido la función dada, la instrucción require_once() comprueba si el archivo especificado ya ha sido incluido y, si es así, no lo vuelve a incluir.
La función wp_handle_upload() maneja las cargas de PHP en WordPress, desinfectando nombres de archivos, comprobando extensiones para el tipo mime y moviendo el archivo al directorio apropiado dentro del directorio uploads.
Antes de añadir la nueva imagen de avatar, llamamos a la función avatar_manager_delete_avatar() para eliminar el antiguo avatar, si hay alguno establecido.
La función wp_insert_attachment() inserta un archivo adjunto en la biblioteca multimedia.
La función wp_generate_attachment_metadata() genera metadatos para un archivo adjunto de imagen; también crea una miniatura y otros tamaños intermedios del archivo adjunto de imagen en función de los tamaños definidos en la Pantalla de configuración de medios.
La función wp_update_attachment_metadata() actualiza los metadatos de un archivo adjunto.
A continuación, llamamos a la función avatar_manager_avatar_resize() para generar una copia de la imagen del avatar con el tamaño predeterminado.
Por último, actualizamos los metadatos para el archivo adjunto y para el usuario que se esté editando actualmente.

Eliminar una imagen de avatar

Ahora, es el momento de hacer que el plugin elimine realmente una imagen de avatar cuando le sea solicitado:

if ( isset( $_GET['avatar_manager_action'] ) && $_GET['avatar_manager_action'] ) {
	global $wp_http_referer;

	$action = $_GET['avatar_manager_action'];

	switch ( $action ) {
		case 'remove-avatar':
			// Deletes avatar image based on attachment ID.
			avatar_manager_delete_avatar( $_GET['avatar_manager_custom_avatar'] );

			break;
	}

	// Gets the link to the users edit profile page in the WordPress admin.
	$edit_user_link = get_edit_user_link( $user_id );

	// Retrieves a modified URL (with) query string.
	$redirect = add_query_arg( 'updated', true, $edit_user_link );

	if ( $wp_http_referer )
		// Retrieves a modified URL (with) query string.
		$redirect = add_query_arg( 'wp_http_referer', urlencode( $wp_http_referer ), $redirect );

	// Redirects the user to a specified absolute URI.
	wp_redirect( $redirect );

	exit;
}

Resumen

Si el valor de la acción solicitada es remove-avatar llamamos a avatar_manager_delete_avatar() para eliminar la imagen de avatar especificada.
La función get_edit_user_link() obtiene el enlace a la página de edición de perfil de los usuarios en el escritorio de WordPress.
La función urlencode() codifica una cadena que se utilizará en una parte de la consulta de una URL.
Al final de la función, llamamos a la función wp_redirect() para redirigir al usuario de nuevo al perfil de usuario actualizado.
La llamada exit termina la ejecución del script; es una construcción de lenguaje y se puede llamar sin paréntesis si no se pasa ningún status.

Paso 4. Recuperar una imagen de avatar personalizada

A continuación, vamos a escribir una función auxiliar para recuperar una imagen de avatar personalizada:

/**
 * Returns user custom avatar based on user ID.
 *
 * @uses get_option() For getting values for a named option.
 * @uses avatar_manager_get_options() For retrieving plugin options.
 * @uses get_userdata() For retrieving user data by user ID.
 * @uses is_ssl() For checking if SSL is being used.
 * @uses add_query_arg() For retrieving a modified URL (with) query string.
 * @uses esc_attr() For escaping HTML attributes.
 * @uses get_user_meta() For retrieving user meta fields.
 * @uses get_post_meta() For retrieving attachment meta fields.
 * @uses wp_get_attachment_image_src() For retrieving an array with the image
 * attributes "url", "width" and "height", of an image attachment file.
 * @uses avatar_manager_avatar_resize() For generating a resized copy of the
 * specified avatar image.
 * @uses update_post_meta() For updating attachment meta fields.
 * @uses apply_filters() For calling the functions added to a filter hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param int $user_id User to update.
 * @param int $size Size of the avatar image
 * @param string $default URL to a default image to use if no avatar is
 * available.
 * @param string $alt Alternative text to use in image tag. Defaults to blank.
 * @return string <img> tag for the user's avatar.
 */
function avatar_manager_get_custom_avatar( $user_id, $size = '', $default = '', $alt = false ) {
	// Returns if showing avatars is not enabled.
	if ( ! get_option( 'show_avatars' ) )
		return false;

	// Retrieves plugin options.
	$options = avatar_manager_get_options();

	if ( empty( $size ) || ! is_numeric( $size ) ) {
		$size = $options['avatar-manager-default-size'];
	} else {
		$size = absint( $size );

		if ( $size < 1 )
			$size = 1;
		elseif ( $size > 512 )
			$size = 512;
	}

	// Retrieves user data by user ID.
	$user = get_userdata( $user_id );

	// Returns if no user data was retrieved.
	if ( empty( $user ) )
		return false;

	$email = $user->user_email;

	if ( empty( $default ) ) {
		// Retrieves values for the named option.
		$avatar_default = get_option( 'avatar_default' );

		if ( empty( $avatar_default ) )
			$default = 'mystery';
		else
			$default = $avatar_default;
	}

	$email_hash = md5( strtolower( trim( $email ) ) );

	if ( is_ssl() )
		$host = 'https://secure.gravatar.com';
	else
		$host = sprintf( 'http://%d.gravatar.com', ( hexdec( $email_hash[0] ) % 2 ) );

	if ( $default == 'mystery' )
		$default = $host . '/avatar/ad516503a11cd5ca435acc9bb6523536?s=' . $size;
	elseif ( $default == 'gravatar_default' )
		$default = '';
	elseif ( strpos( $default, 'http://' ) === 0 )
		// Retrieves a modified URL (with) query string.
		$default = add_query_arg( 's', $size, $default );

	if ( $alt === false )
		$alt = '';
	else
		// Escapes HTML attributes.
		$alt = esc_attr( $alt );

	// Retrieves values for the named option.
	$avatar_rating = get_option( 'avatar_rating' );

	// Retrieves user meta field based on user ID.
	$custom_avatar = get_user_meta( $user_id, 'avatar_manager_custom_avatar', true );

	// Returns if no attachment ID was retrieved.
	if ( empty( $custom_avatar ) )
		return false;

	// Retrieves attachment meta field based on attachment ID.
	$custom_avatar_rating = get_post_meta( $custom_avatar, '_avatar_manager_custom_avatar_rating', true );

	$ratings['G']  = 1;
	$ratings['PG'] = 2;
	$ratings['R']  = 3;
	$ratings['X']  = 4;

	if ( $ratings[ $custom_avatar_rating ] <= $ratings[ $avatar_rating ] ) {
		// Retrieves attachment meta field based on attachment ID.
		$avatar = get_post_meta( $custom_avatar, '_avatar_manager_custom_avatar', true );

		if ( empty( $avatar[ $size ] ) ) {
			// Retrieves an array with the image attributes "url", "width"
			// and "height", of the image attachment file.
			$url = wp_get_attachment_image_src( $custom_avatar, 'full' );

			// Generates a resized copy of the avatar image.
			$avatar[ $size ] = avatar_manager_avatar_resize( $url[0], $size );

			// Updates attachment meta field based on attachment ID.
			update_post_meta( $custom_avatar, '_avatar_manager_custom_avatar', $avatar );
		}

		$src    = $avatar[ $size ]['url'];
		$avatar = '<img alt="' . $alt . '" class="avatar avatar-' . $size . ' photo avatar-default" height="' . $size . '" src="' . $src . '" width="' . $size . '">';
	} else {
		$src  = $host . '/avatar/';
		$src .= $email_hash;
		$src .= '?s=' . $size;
		$src .= '&d=' . urlencode( $default );
		$src .= '&forcedefault=1';

		$avatar = '<img alt="' . $alt . '" class="avatar avatar-' . $size . ' photo avatar-default" height="' . $size . '" src="' . $src . '" width="' . $size . '">';
	}

	// Calls the functions added to avatar_manager_get_custom_avatar
	// filter hook.
	return apply_filters( 'avatar_manager_get_custom_avatar', $avatar, $user_id, $size, $default, $alt );
}

Resumen

La función avatar_manager_get_custom_avatar devuelve una imagen de avatar personalizada basada en el ID de usuario o false si no se ha habilitado la visualización de avatares. La función recupera las opciones del plugin, desinfecta el parámetro $size y dá salida a los atributos HTML de la variable $alt.
A continuación, recupera una imagen predeterminada para usarla en lugar de la imagen de avatar si la clasificación de este no coincide. Se genera una copia redimensionada de la imagen de avatar a petición si el tamaño solicitado no coincide con un archivo de imagen existente.
La función get_userdata() devuelve un objeto WP_User con la información relativa al usuario cuyo ID le ha sido pasado.
La función md5() devuelve el hash MD5 para la cadena proporcionada.
La función strtolower() devuelve la cadena proporcionada pero con todos los caracteres alfabéticos convertidos a minúsculas.
La llamada is_ssl() comprueba si se está utilizando SSL.
La función sprintf() devuelve una cadena con formato.
La función hexdec() devuelve el equivalente decimal del número hexadecimal especificado.
La llamada strpos() encuentra la posición numérica de la primera aparición de needle en la cadena haystack.
La función wp_get_attachment_image_src() devuelve una matriz con los atributos de imagen url, width y height de un archivo de datos adjuntos de imagen.
Por último, utilizamos la función apply_filters() para llamar a las funciones añadidas al enlace de filtro avatar_manager_get_custom_avatar.

Paso 5. Recuperar una imagen de avatar

Básicamente, la siguiente función es la función principal de nuestro plugin:

/**
 * Returns the avatar for a user who provided a user ID or email address.
 *
 * @uses get_option() For getting values for a named option.
 * @uses avatar_manager_get_options() For retrieving plugin options.
 * @uses get_userdata() For retrieving user data by user ID.
 * @uses avatar_manager_get_custom_avatar() For retrieving user custom avatar
 * based on user ID.
 * @uses apply_filters() For calling the functions added to a filter hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param int|string|object $id_or_email A user ID, email address, or comment
 * object.
 * @param int $size Size of the avatar image
 * @param string $default URL to a default image to use if no avatar is
 * available.
 * @param string $alt Alternative text to use in image tag. Defaults to blank.
 * @return string <img> tag for the user's avatar.
 */
function avatar_manager_get_avatar( $avatar = '', $id_or_email, $size = '', $default = '', $alt = false ) {
	// Returns if showing avatars is not enabled.
	if ( ! get_option( 'show_avatars' ) )
		return false;

	// Retrieves plugin options.
	$options = avatar_manager_get_options();

	if ( empty( $size ) || ! is_numeric( $size ) ) {
		$size = $options['avatar-manager-default-size'];
	} else {
		$size = absint( $size );

		if ( $size < 1 )
			$size = 1;
		elseif ( $size > 512 )
			$size = 512;
	}

	$email = '';

	if ( is_numeric( $id_or_email ) ) {
		$id = (int) $id_or_email;

		// Retrieves user data by user ID.
		$user = get_userdata( $id );

		if ( $user )
			$email = $user->user_email;
	} elseif ( is_object( $id_or_email ) ) {
		if ( ! empty( $id_or_email->user_id ) ) {
			$id = (int) $id_or_email->user_id;

			// Retrieves user data by user ID.
			$user = get_userdata( $id );

			if ( $user )
				$email = $user->user_email;
		} elseif ( ! empty( $id_or_email->comment_author_email ) ) {
			$email = $id_or_email->comment_author_email;
		}
	} else {
		$email = $id_or_email;

		if ( $id = email_exists( $email ) )
			// Retrieves user data by user ID.
			$user = get_userdata( $id );
	}

	if ( isset( $user ) )
		$avatar_type = $user->avatar_manager_avatar_type;
	else
		return $avatar;

	if ( $avatar_type == 'custom' )
		// Retrieves user custom avatar based on user ID.
		$avatar = avatar_manager_get_custom_avatar( $user->ID, $size, $default, $alt );

	// Calls the functions added to avatar_manager_get_avatar filter hook.
	return apply_filters( 'avatar_manager_get_avatar', $avatar, $id_or_email, $size, $default, $alt );
}

add_filter( 'get_avatar', 'avatar_manager_get_avatar', 10, 5 );

Resumen

La función avatar_manager_get_avatar() devuelve el avatar de un usuario que proporcionó un ID de usuario o una dirección de correo electrónico, o false si no está habilitada la visualización de avatares.
Usamos el filtro get_avatar para cambiar la salida de la función get_avatar(). Nuestra función recupera las opciones del plugin, desinfecta el parámetro $size y encuentra el ID del usuario especificado.
A continuación, devuelve el resultado de la llamada a la función avatar_manager_get_custom_avatar(), o la salida no modificada de get_avatar() si el usuario no utiliza un avatar personalizado.
La llamada is_object() busca si una variable es un objeto.
La función email_exists() comprueba si una dirección de correo electrónico determinada ya ha sido registrada en un nombre de usuario y devuelve ese ID de usuario, o false si no existe ninguno.

Para comprobar el resultado, dirígete a la pantalla Usuarios -> Tu perfil.

Las opciones del plugin Avatar Manager en la pantalla de usuario Tu perfil

Busca una imagen y cárgala. Ahora, deberías poder elegir entre usar Gravatar o la imagen de avatar personalizada que acabas de subir.

Paso 6. Eliminar ganchos de filtro innecesarios

Si vas a la pantalla discusión de configuración, notarás que los avatares de la configuración de Avatar predeterminada se reemplazan por tu avatar personalizado. Para solucionar este problema, restauraremos los avatares predeterminados eliminando nuestra función personalizada cuando no sea necesario con la ayuda del gancho de filtro avatar_defaults. Para ello, añade el siguiente código:

/**
 * Prevents custom avatars from being applied to the Default Avatar setting.
 *
 * @uses remove_filter() For removing a function attached to a specified action
 * hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param array $avatar_defaults An associative array with default avatars.
 * @return array An associative array with default avatars.
 */
function avatar_manager_avatar_defaults( $avatar_defaults ) {
	// Removes the avatar_manager_get_avatar function attached to get_avatar
	// action hook.
	remove_filter( 'get_avatar', 'avatar_manager_get_avatar' );

	return $avatar_defaults;
}

add_filter( 'avatar_defaults', 'avatar_manager_avatar_defaults', 10, 1 );

Para evitar que los avatares personalizados se apliquen a la configuración de Avatar predeterminado, llamamos a la función remove_filter(). Elimina una función asociada a un gancho de filtro especificado. Este método puede utilizarse para eliminar las funciones predeterminadas asociadas a un gancho de filtro concreto y posiblemente reemplazarlas con un sustituto.

Paso 7. Visualizar los estados personalizados de medios

La pantalla de la Biblioteca de medios te permite editar, ver y eliminar imágenes, vídeos, grabaciones y archivos cargados previamente en tu blog. Para identificar un archivo adjunto que se utiliza como imagen de avatar, vamos a mostrar un estado de medios personalizado:

/**
 * Displays media states for avatar images.
 *
 * @uses get_post_meta() For retrieving attachment meta fields.
 * @uses __() For retrieving the translated string from the translate().
 * @uses apply_filters() For calling the functions added to a filter hook.
 *
 * @since Avatar Manager 1.0.0
 *
 * @param array $media_states An associative array with media states.
 * @return array An associative array with media states.
 */
function avatar_manager_display_media_states( $media_states ) {
	global $post;

	// Retrieves attachment meta field based on attachment ID.
	$meta_avatar = get_post_meta( $post->ID, '_avatar_manager_is_custom_avatar', true );

	if ( ! empty( $meta_avatar ) )
		$media_states[] = __( 'Avatar Image', 'avatar-manager' );

	// Calls the functions added to avatar_manager_display_media_states filter
	// hook.
	return apply_filters( 'avatar_manager_display_media_states', $media_states );
}

add_filter( 'display_media_states', 'avatar_manager_display_media_states', 10, 1 );

El filtro display_media_states se utiliza para mostrar estados de medios personalizados para los elementos adjuntos que se hayan añadido a la Biblioteca de medios. Usamos la variable global $post para obtener el ID del archivo adjunto actual. Si el campo personalizado _avatar_manager_is_custom_avatar no está vacío, el archivo adjunto es una imagen de avatar, por lo que le añadimos un estado de medios personalizado.

Si no tienes ninguna imagen de avatar personalizada configurada, sube una y dirígete a la pantalla de la Biblioteca de medios.

Los estados de medios del plugin Avatar Manager en la pantalla de la Biblioteca de medios

Ten en cuenta que cada archivo adjunto que se utiliza como una imagen de avatar personalizada tiene la cadena de imagen de avatar anexada junto a su nombre de archivo.

Paso 8. Añadir el desinstalador

Para manejar el proceso de desinstalación, un plugin debe crear un archivo llamado uninstall.php en el directorio base del plugin en lugar de usar register_uninstall_hook(). Si este archivo existe, será llamado durante el proceso de desinstalación omitiendo el gancho de desinstalación. Para ello, abre avatar-manager/uninstall.php y añade el siguiente código:

<?php
/**
 * @package Avatar_Manager
 * @subpackage Uninstaller
 */

// Exits if uninstall is not called from WordPress.
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) )
	exit;

if ( ! function_exists( 'avatar_manager_delete_avatar' ) )
	include_once( 'avatar-manager.php' );

// Deletes plugin options.
delete_option( 'avatar_manager' );

// An associative array with criteria to match.
$args = array(
	'meta_key' => 'avatar_manager_custom_avatar'
);

// Retrieves an array of users matching the criteria given in $args.
$users = get_users( $args );

foreach ( $users as $user ) {
	// Deletes avatar image based on attachment ID.
	avatar_manager_delete_avatar( $user->avatar_manager_custom_avatar );
}
?>

Cuando se utiliza uninstall.php el plugin siempre debe comprobar la constante WP_UNINSTALL_PLUGIN, antes de ejecutarse. La constante WP_UNINSTALL_PLUGIN es definida por WordPress en tiempo de ejecución durante una desinstalación del plugin y no estará presente si uninstall.php se solicita directamente. defined() comprueba si existe una determinada constante con nombre. La instrucción include_once incluye y evalúa el archivo especificado durante la ejecución del script; si el código de un archivo ya ha sido incluido, no se incluirá nuevamente. La función delete_option() elimina una opción con nombre de la tabla options de la base de datos.

Paso 9. Internacionalizar y traducir el plugin

Una vez hayas creado la programación para tu plugin, otra consideración es la internacionalización. La internacionalización, abreviada a menudo como i18n, es el proceso de configuración de software para que pueda ser localizado; localización, o l10n, es el proceso de traducción del texto mostrado por el software en diferentes idiomas. WordPress utiliza las bibliotecas y herramientas gettext para i18n.

Es muy recomendable que internacionalices tu plugin, para que los usuarios de diferentes países puedan localizarlo.

Cadenas traducibles

Para hacer una cadena traducible, solo tienes que ajustar la cadena original en una llamada a la función __(). Si el código debe hacerse eco de la cadena en el navegador, utiliza en su lugar la función _e(). Como habrás notado, ya lo hemos hecho en nuestro plugin.

Dominios de texto

Un dominio de texto es un identificador único, que se asegura de que WordPress pueda distinguir entre todas las traducciones cargadas. Usar el nombre base de tu plugin siempre es una buena opción. Puedes cargar las cadenas traducidas del plugin llamando a la función load_plugin_textdomain(), algo que ya hemos hecho en la primera parte de nuestro tutorial.

Archivos PO

Ahora, tenemos que crear un archivo .po para los traductores. Para ello, usaremos el software de traducción Poedit. Una vez lo hayas descargado, haz clic en Archivo > Nuevo catálogo... para configurar un nuevo catálogo. Debería abrirse una nueva ventana. Dirígete a la pestaña Información del proyecto e introduce Avatar Manager como nombre del proyecto.

Ficha Información del proyecto de Poedit en la ventana Configuración

En la pestaña Rutas, dejemos la ruta de acceso base como . que hace referencia al directorio en el que se encuentra el catálogo.

La ficha Rutas de Poedit situada bajo la ventana Configuración

A continuación, dirígete a la pestaña Palabras clave. Elimina todos los elementos que aparecen allí, y añade estas palabras clave: __, _e, _n y _x.

Ficha Palabras clave de Poedit en la ventana Configuración

Pulsa OK y guarda el archivo como avatar-manager/languages/avatar-manager-default.po. Ahora, el archivo ya está listo para su traducción.

Ventana principal de Poedit

Traduce todas las cadenas que quieras y, a continuación, guarda el archivo como avatar-manager/languages/avatar-manager-{locale}.po. Locale es el código de idioma y/o código de país que definiste en la constante WPLANG en el archivo wp-config.php.

Archivos MO

Un archivo .mo es un archivo binario que contiene todas las cadenas originales y sus traducciones en un formato adecuado para la rápida extracción de la traducción. La conversión se realiza automáticamente si va a Editar > Preferencias > Editor y marcas Compilar automáticamente el archivo MO al guardar.

Paso 10. Publicación y promoción de un plugin

Esta sección revisamos los pasos necesarios para tomar un plugin que hayas creado y conseguir distribuirlo ampliamente.

Envío al directorio de plugins de WordPress

La forma más rápida, sencilla y mejor de distribuir tu plugin es cargarlo en el Directorio de plugins de WordPress. Para obtener más detalles sobre cómo enviar tu plugin, consulta la página de Información para desarrolladores o dirígete directamente a la página de envío de plugins.

Promocionar y documentar tu plugin

Para enviar y promocionar tu plugin entre la Comunidad de WordPress, crea primero en tu sitio una página para el plugin con instrucciones completas y bien escritas. Incluye un enlace a esta página con explicaciones en la cabecera del plugin, para que las personas puedan buscar fácilmente actualizaciones, más información y ayuda.

Si decides enviar tu plugin al Directorio de plugins de WordPress, haz también que esta información sea lo más clara posible de forma que puedan categorizar y ayudar a otros a entender la utilidad de tu plugin. También tienes que crear un archivo readme.txt en un formato estándar, e incluirlo en tu plugin.

Conclusión

Con esto concluimos nuestro tutorial; ahora, tenemos un plugin completamente en funcionamiento y hemos aprendido algunos consejos y trucos prácticos sobre el desarrollo de plugins de WordPress. La idea detrás de este plugin comenzó como una característica solicitada en el núcleo de WordPress; Me encantaría oír tus opiniones al respecto. ¿Mejora el flujo de trabajo actual? ¿Te resultaría útil un enfoque similar pero para la gestión de imágenes de Gravatar directamente desde la pantalla de tu perfil?

Como extra, el plugin Avatar Manager también está disponible en el Directorio de plugins de WordPress y en GitHub. Compruébalo para mantenerte al día con las últimas actualizaciones. ¡Gracias por leerme!

Referencias

WordPress Coding Standards: Información general sobre los estándares de codificación para el desarrollo de WordPress.
Writing a Plugin: El mejor punto de partida para aprender sobre cómo desarrollar plugins de WordPress.
Plugin API: Descripción sobre cómo utilizar ganchos de acción y filtros en tu plugin de WordPress, y funciones principales que los plugins pueden invalidar.
Function Reference: Un artículo con muchas de las funciones principales de WordPress útiles para los desarrolladores de plugins y temas; enumera la mayoría de las funciones más importantes, excluyendo las etiquetas de plantilla.
I18n for WordPress Developers: Internacionalización, incluyendo una sección sobre cómo internacionalizar tu plugin.
Plugin Submission and Promotion: Una vez haya escrito tu plugin, aquí tienes algunas sugerencias para distribuirlo ampliamente.

Enlaces externos

Avatar Manager en el Directorio de plugins de WordPress: Página oficial del plugin Avatar Manager
Avatar Manager en GitHub: Código fuente del plugin Avatar Manager.