Estas en: Home > registro

Entradas etiquetadas con registro

Cron Job WordPress

WordPress 3.x para desarrolladores: Temas y plantillas, functions.php

0

Como ya llevamos varias plantillas creadas con algunas llamadas a funciones del archivo functions.php, vamos a crearlo y añadir esas funciones, después continuaremos añadiendo más plantillas.

 

FUNCTIONS.PHP

Creamos el archivo functions.php y añadimos el siguiente código:

[codesyntax lang=»php»]

<?php

/**
 * Set the content width based on the theme's design and stylesheet.
 */
if ( ! isset( $content_width ) )
	$content_width = 584;

[/codesyntax]

Este código creara una variable que nos indicará el ancho que tendrá el contenido.

[codesyntax lang=»php»]

<?php

/**
 * Tell WordPress to run newtheme_setup() when the 'after_setup_theme' hook is run.
 */
add_action( 'after_setup_theme', 'newtheme_setup' );

if ( ! function_exists( 'newtheme_setup' ) ):

function newtheme_setup() {

}

endif;

[/codesyntax]

 

Le decimos a WordPress que ejecute newtheme_setup cuando el hook after_setup_theme esté funcionando. Creamos un condicional para comprobar que la función newtheme_setup no ha sido aun creada, y creamos la función.

Dentro de newtheme_setup añadiremos las siguientes lineas de código:

[codesyntax lang=»php»]

<?php

	load_theme_textdomain( 'newtheme', get_template_directory() . '/languages' );

[/codesyntax]

Esta línea cargará el archivo de idioma correspondiente.

[codesyntax lang=»php»]

<?php

	add_editor_style();

[/codesyntax]

Le indicamos a WordPress que cargue el editor de estilos. Para ello WordPress buscará el archivo editor-style.css dentro de la carpeta del tema, por tanto copiaremos los archivos editor-style.css y editor-style-rtl.css del tema Twenty Eleven a nuestro tema.

[codesyntax lang=»php»]

<?php

	require( get_template_directory() . '/inc/theme-options.php' );
	require( get_template_directory() . '/inc/widgets.php' );

[/codesyntax]

Estas dos lineas cargan los archivos de las opciones del tema que se mostrarán en la administración y los widgets de los que disponga el tema.

[codesyntax lang=»php»]

<?php

	add_theme_support( 'automatic-feed-links' );

[/codesyntax]

Le indicamos a WordPress que los links de este tema se añadirán a un archivo rss que se creará automáticamente. Más sobre otros argumentos de esta función: http://codex.wordpress.org/Function_Reference/add_theme_support

[codesyntax lang=»php»]

<?php

	register_nav_menu( 'primary', __( 'Primary Menu', 'newtheme' ) );

[/codesyntax]

Registramos la barra de menú de la cabecera.

[codesyntax lang=»php»]

<?php
	add_theme_support( 'post-formats', array( 'aside', 'link', 'gallery', 'status', 'quote', 'image' ) );

[/codesyntax]

Añadimos soporte para varios tipos de formato de posts.

[codesyntax lang=»php»]

<?php

	$theme_options = newtheme_get_theme_options();
	if ( 'dark' == $theme_options['color_scheme'] )
		$default_background_color = '1d1d1d';
	else
		$default_background_color = 'f1f1f1';

	// Add support for custom backgrounds.
	add_theme_support( 'custom-background', array(
		// Let WordPress know what our default background color is.
		// This is dependent on our current color scheme.
		'default-color' => $default_background_color,
	) );

[/codesyntax]

Primero recuperamos las opciones del tema a través de la función newtheme_get_theme_options(), que se encuentra en el archivo inc/theme_options.php, el cual crearemos más delante.

Comprobamos que tipo de esquema de estilos se ha elegido y guardamos en la variable $default_background_color el valor correspondiente.

Le indicamos a WordPress el color de nuestro fondo de página.

[codesyntax lang=»php»]

<?php

	add_theme_support( 'post-thumbnails' );

[/codesyntax]

Le indicamos a WordPress que este tema utilizará imágenes destacadas o thumbnails.

[codesyntax lang=»php»]

<?php

	$custom_header_support = array(
		// The default header text color.
		'default-text-color' => '000',
		// The height and width of our custom header.
		'width' => apply_filters( 'newtheme_header_image_width', 1000 ),
		'height' => apply_filters( 'newtheme_header_image_height', 288 ),
		// Support flexible heights.
		'flex-height' => true,
		// Random image rotation by default.
		'random-default' => true,
		// Callback for styling the header.
		'wp-head-callback' => 'newtheme_header_style',
		// Callback for styling the header preview in the admin.
		'admin-head-callback' => 'newtheme_admin_header_style',
		// Callback used to display the header preview in the admin.
		'admin-preview-callback' => 'newtheme_admin_header_image',
	);

	add_theme_support( 'custom-header', $custom_header_support );

[/codesyntax]

Creamos un array con los encabezados personalizados y se lo indicamos a WordPress.

[codesyntax lang=»php»]

<?php

	if ( ! function_exists( 'get_custom_header' ) ) {
		// This is all for compatibility with versions of WordPress prior to 3.4.
		define( 'HEADER_TEXTCOLOR', $custom_header_support['default-text-color'] );
		define( 'HEADER_IMAGE', '' );
		define( 'HEADER_IMAGE_WIDTH', $custom_header_support['width'] );
		define( 'HEADER_IMAGE_HEIGHT', $custom_header_support['height'] );
		add_custom_image_header( $custom_header_support['wp-head-callback'], $custom_header_support['admin-head-callback'], $custom_header_support['admin-preview-callback'] );
		add_custom_background();
	}

[/codesyntax]

En el caso de que se utilizase este tema con una versión de WordPress inferior a la 3.4 creamos varias constantes, y añadimos las cabeceras personalizadas y el fondo a WordPress.

[codesyntax lang=»php»]

<?php

	set_post_thumbnail_size( $custom_header_support['width'], $custom_header_support['height'], true );

[/codesyntax]

Configuramos la imagen destacada definiendo un ancho y alto.

[codesyntax lang=»php»]

<?php

	add_image_size( 'large-feature', $custom_header_support['width'], $custom_header_support['height'], true );
	// Used for featured posts if a large-feature doesn't exist.
	add_image_size( 'small-feature', 500, 300 );

[/codesyntax]

Añadimos la imagen a la cabecera definiendo su ancho y alto, además añadimos una imagen más pequeña para los post en el caso de que no existe imagen para la cabecera.

[codesyntax lang=»php»]

<?php

	register_default_headers( array(
		'wheel' => array(
			'url' => '%s/images/headers/wheel.jpg',
			'thumbnail_url' => '%s/images/headers/wheel-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Wheel', 'newtheme' )
		),
		'shore' => array(
			'url' => '%s/images/headers/shore.jpg',
			'thumbnail_url' => '%s/images/headers/shore-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Shore', 'newtheme' )
		),
		'trolley' => array(
			'url' => '%s/images/headers/trolley.jpg',
			'thumbnail_url' => '%s/images/headers/trolley-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Trolley', 'newtheme' )
		),
		'pine-cone' => array(
			'url' => '%s/images/headers/pine-cone.jpg',
			'thumbnail_url' => '%s/images/headers/pine-cone-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Pine Cone', 'newtheme' )
		),
		'chessboard' => array(
			'url' => '%s/images/headers/chessboard.jpg',
			'thumbnail_url' => '%s/images/headers/chessboard-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Chessboard', 'newtheme' )
		),
		'lanterns' => array(
			'url' => '%s/images/headers/lanterns.jpg',
			'thumbnail_url' => '%s/images/headers/lanterns-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Lanterns', 'newtheme' )
		),
		'willow' => array(
			'url' => '%s/images/headers/willow.jpg',
			'thumbnail_url' => '%s/images/headers/willow-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Willow', 'newtheme' )
		),
		'hanoi' => array(
			'url' => '%s/images/headers/hanoi.jpg',
			'thumbnail_url' => '%s/images/headers/hanoi-thumbnail.jpg',
			/* translators: header image description */
			'description' => __( 'Hanoi Plant', 'newtheme' )
		)
	) );

[/codesyntax]

Este es el paquete de imágenes que el tema Twenty Eleven trae por defecto, nosotros haremos lo mismo. Si no lo habéis hecho ya, copiad la carpeta images del tema Twenty Eleven a nuestro tema.

El marcador %s indica que se debe sustituir por la uri del tema.

Como esta función tiene llamadas a otras funciones dentro del mismo archivo functions.php, vamos a crearlas.

En primer lugar crearemos la función newtheme_header_style():

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_header_style' ) ) :
/**
 * Styles the header image and text displayed on the blog
 */
function newtheme_header_style() {
	$text_color = get_header_textcolor();

	// If no custom options for text are set, let's bail.
	if ( $text_color == HEADER_TEXTCOLOR )
		return;

	// If we get this far, we have custom styles. Let's do this.
	?>
	<style type="text/css">
	<?php
		// Has the text been hidden?
		if ( 'blank' == $text_color ) :
	?>
		#site-title,
		#site-description {
			position: absolute !important;
			clip: rect(1px 1px 1px 1px); /* IE6, IE7 */
			clip: rect(1px, 1px, 1px, 1px);
		}
	<?php
		// If the user has set a custom color for the text use that
		else :
	?>
		#site-title a,
		#site-description {
			color: #<?php echo $text_color; ?> !important;
		}
	<?php endif; ?>
	</style>
	<?php
}
endif; // newtheme_header_style

[/codesyntax]

Simplemente en esta función se generan los estilos para el título y la descripción que se ubican en la cabecera de la página.

Creamos el método newtheme_admin_header_style():

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_admin_header_style' ) ) :
/**
 * Styles the header image displayed on the Appearance > Header admin panel.
 *
 * Referenced via add_theme_support('custom-header') in newtheme_setup().
 */
function newtheme_admin_header_style() {
?>
	<style type="text/css">
	.appearance_page_custom-header #headimg {
		border: none;
	}
	#headimg h1,
	#desc {
		font-family: "Helvetica Neue", Arial, Helvetica, "Nimbus Sans L", sans-serif;
	}
	#headimg h1 {
		margin: 0;
	}
	#headimg h1 a {
		font-size: 32px;
		line-height: 36px;
		text-decoration: none;
	}
	#desc {
		font-size: 14px;
		line-height: 23px;
		padding: 0 0 3em;
	}
	<?php
		// If the user has set a custom color for the text use that
		if ( get_header_textcolor() != HEADER_TEXTCOLOR ) :
	?>
		#site-title a,
		#site-description {
			color: #<?php echo get_header_textcolor(); ?>;
		}
	<?php endif; ?>
	#headimg img {
		max-width: 1000px;
		height: auto;
		width: 100%;
	}
	</style>
<?php
}
endif; // newhtme_admin_header_style

[/codesyntax]

Esta función permite dar estilos a la imagen de la cabecera dentro de su apartado de opciones en la administración de WordPress, donde se podrá configurar cómo se ve la imagen.

Creamos la función newtheme_admin_header_image():

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_admin_header_image' ) ) :
/**
 * Custom header image markup displayed on the Appearance > Header admin panel.
 *
 * Referenced via add_theme_support('custom-header') in newtheme_setup().
 */
function newtheme_admin_header_image() { ?>
	<div id="headimg">
		<?php
		$color = get_header_textcolor();
		$image = get_header_image();
		if ( $color && $color != 'blank' )
			$style = ' style="color:#' . $color . '"';
		else
			$style = ' style="display:none"';
		?>
		<h1><a id="name"<?php echo $style; ?> onclick="return false;" href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></h1>
		<div id="desc"<?php echo $style; ?>><?php bloginfo( 'description' ); ?></div>
		<?php if ( $image ) : ?>
			<img src="<?php echo esc_url( $image ); ?>" alt="" />
		<?php endif; ?>
	</div>
<?php }
endif; // newtheme_admin_header_image

[/codesyntax]

Esta función crea el código html que mostrará la imagen, el título y la descripción en su respectiva zona de opciones de la administración de WordPress, para que el usuario pueda ver como quedaría.

[codesyntax lang=»php»]

<?php

/**
 * Sets the post excerpt length to 40 words.
 *
 * To override this length in a child theme, remove the filter and add your own
 * function tied to the excerpt_length filter hook.
 */
function newtheme_excerpt_length( $length ) {
	return 40;
}
add_filter( 'excerpt_length', 'newtheme_excerpt_length' );

[/codesyntax]

Esta función establece la longitud del extracto de un post a 40 palabras.

[codesyntax lang=»php»]

<?php

/**
 * Returns a "Continue Reading" link for excerpts
 */
function newtheme_continue_reading_link() {
	return ' <a href="'. esc_url( get_permalink() ) . '">' . __( 'Continue reading <span class="meta-nav">&rarr;</span>', 'newtheme' ) . '</a>';
}

[/codesyntax]

Esta función devuelve el link con el texto «Seguir leyendo…» en los extractos de los posts.

[codesyntax lang=»php»]

<?php

/**
 * Replaces "[...]" (appended to automatically generated excerpts) with an ellipsis and newtheme_continue_reading_link().
 *
 * To override this in a child theme, remove the filter and add your own
 * function tied to the excerpt_more filter hook.
 */
function newtheme_auto_excerpt_more( $more ) {
	return ' &hellip;' . newtheme_continue_reading_link();
}
add_filter( 'excerpt_more', 'newtheme_auto_excerpt_more' );

[/codesyntax]

Esta función remplaza el texto «[…]» por «…» utilizando «&hellip;» para ello, y el link de newtheme_continue_reading_link()

[codesyntax lang=»php»]

<?php

/**
 * Adds a pretty "Continue Reading" link to custom post excerpts.
 *
 * To override this link in a child theme, remove the filter and add your own
 * function tied to the get_the_excerpt filter hook.
 */
function newtheme_custom_excerpt_more( $output ) {
	if ( has_excerpt() && ! is_attachment() ) {
		$output .= newtheme_continue_reading_link();
	}
	return $output;
}
add_filter( 'get_the_excerpt', 'newtheme_custom_excerpt_more' );

[/codesyntax]

Añade la salida de newtheme_continue_reading_link() a los extractos personalizados de los posts.

[codesyntax lang=»php»]

<?php

/**
 * Get our wp_nav_menu() fallback, wp_page_menu(), to show a home link.
 */
function newtheme_page_menu_args( $args ) {
	$args['show_home'] = true;
	return $args;
}
add_filter( 'wp_page_menu_args', 'newtheme_page_menu_args' );

[/codesyntax]

Esta función hace que en nuestro menú de navegación aparezca un link hacía la página principal.

[codesyntax lang=»php»]

<?php

/**
 * Register our sidebars and widgetized areas. Also register the default Epherma widget.
 */
function newtheme_widgets_init() {

	register_widget( 'New_Theme_Ephemera_Widget' );

	register_sidebar( array(
		'name' => __( 'Main Sidebar', 'newtheme' ),
		'id' => 'sidebar-1',
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget' => "</aside>",
		'before_title' => '<h3 class="widget-title">',
		'after_title' => '</h3>',
	) );

	register_sidebar( array(
		'name' => __( 'Showcase Sidebar', 'newtheme' ),
		'id' => 'sidebar-2',
		'description' => __( 'The sidebar for the optional Showcase Template', 'newtheme' ),
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget' => "</aside>",
		'before_title' => '<h3 class="widget-title">',
		'after_title' => '</h3>',
	) );

	register_sidebar( array(
		'name' => __( 'Footer Area One', 'newtheme' ),
		'id' => 'sidebar-3',
		'description' => __( 'An optional widget area for your site footer', 'newtheme' ),
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget' => "</aside>",
		'before_title' => '<h3 class="widget-title">',
		'after_title' => '</h3>',
	) );

	register_sidebar( array(
		'name' => __( 'Footer Area Two', 'newtheme' ),
		'id' => 'sidebar-4',
		'description' => __( 'An optional widget area for your site footer', 'newtheme' ),
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget' => "</aside>",
		'before_title' => '<h3 class="widget-title">',
		'after_title' => '</h3>',
	) );

	register_sidebar( array(
		'name' => __( 'Footer Area Three', 'newtheme' ),
		'id' => 'sidebar-5',
		'description' => __( 'An optional widget area for your site footer', 'newtheme' ),
		'before_widget' => '<aside id="%1$s" class="widget %2$s">',
		'after_widget' => "</aside>",
		'before_title' => '<h3 class="widget-title">',
		'after_title' => '</h3>',
	) );
}
add_action( 'widgets_init', 'newtheme_widgets_init' );

[/codesyntax]

Esta función registra nuestro widget que crearemos en el archivo inc/widgets.php, y las cinco sidebars que añade el tema a diferentes partes de la página.

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_content_nav' ) ) :
/**
 * Display navigation to next/previous pages when applicable
 */
function newtheme_content_nav( $nav_id ) {
	global $wp_query;

	if ( $wp_query->max_num_pages > 1 ) : ?>
		<nav id="<?php echo $nav_id; ?>">
			<h3 class="assistive-text"><?php _e( 'Post navigation', 'newtheme' ); ?></h3>
			<div class="nav-previous"><?php next_posts_link( __( '<span class="meta-nav">&larr;</span> Older posts', 'newtheme' ) ); ?></div>
			<div class="nav-next"><?php previous_posts_link( __( 'Newer posts <span class="meta-nav">&rarr;</span>', 'newtheme' ) ); ?></div>
		</nav><!-- #nav-above -->
	<?php endif;
}
endif; // newtheme_content_nav

[/codesyntax]

Muestra los links para mostrar la siguiente o anterior página de posts cuando sea aplicable.

[codesyntax lang=»php»]

<?php

/**
 * Return the URL for the first link found in the post content.
 *
 * @return string|bool URL or false when no link is present.
 */
function newtheme_url_grabber() {
	if ( ! preg_match( '/<a\s[^>]*?href=[\'"](.+?)[\'"]/is', get_the_content(), $matches ) )
		return false;

	return esc_url_raw( $matches[1] );
}

[/codesyntax]

Devuelve la url del primer link encontrado en el contenido del post.

[codesyntax lang=»php»]

<?php

/**
 * Count the number of footer sidebars to enable dynamic classes for the footer
 */
function newtheme_footer_sidebar_class() {
	$count = 0;

	if ( is_active_sidebar( 'sidebar-3' ) )
		$count++;

	if ( is_active_sidebar( 'sidebar-4' ) )
		$count++;

	if ( is_active_sidebar( 'sidebar-5' ) )
		$count++;

	$class = '';

	switch ( $count ) {
		case '1':
			$class = 'one';
			break;
		case '2':
			$class = 'two';
			break;
		case '3':
			$class = 'three';
			break;
	}

	if ( $class )
		echo 'class="' . $class . '"';
}

[/codesyntax]

Cuenta el número de sidebars habilitados para el pie de página y devuelve la clase que corresponda.

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_comment' ) ) :
/**
 * Template for comments and pingbacks.
 *
 * To override this walker in a child theme without modifying the comments template
 * simply create your own newtheme_comment(), and that function will be used instead.
 *
 * Used as a callback by wp_list_comments() for displaying the comments.
 *
 */
function newtheme_comment( $comment, $args, $depth ) {
	$GLOBALS['comment'] = $comment;
	switch ( $comment->comment_type ) :
		case 'pingback' :
		case 'trackback' :
	?>
	<li class="post pingback">
		<p><?php _e( 'Pingback:', 'newtheme' ); ?> <?php comment_author_link(); ?><?php edit_comment_link( __( 'Edit', 'newtheme' ), '<span class="edit-link">', '</span>' ); ?></p>
	<?php
			break;
		default :
	?>
	<li <?php comment_class(); ?> id="li-comment-<?php comment_ID(); ?>">
		<article id="comment-<?php comment_ID(); ?>" class="comment">
			<footer class="comment-meta">
				<div class="comment-author vcard">
					<?php
						$avatar_size = 68;
						if ( '0' != $comment->comment_parent )
							$avatar_size = 39;

						echo get_avatar( $comment, $avatar_size );

						/* translators: 1: comment author, 2: date and time */
						printf( __( '%1$s on %2$s <span class="says">said:</span>', 'newtheme' ),
							sprintf( '<span class="fn">%s</span>', get_comment_author_link() ),
							sprintf( '<a href="%1$s"><time pubdate datetime="%2$s">%3$s</time></a>',
								esc_url( get_comment_link( $comment->comment_ID ) ),
								get_comment_time( 'c' ),
								/* translators: 1: date, 2: time */
								sprintf( __( '%1$s at %2$s', 'newtheme' ), get_comment_date(), get_comment_time() )
							)
						);
					?>

					<?php edit_comment_link( __( 'Edit', 'newtheme' ), '<span class="edit-link">', '</span>' ); ?>
				</div><!-- .comment-author .vcard -->

				<?php if ( $comment->comment_approved == '0' ) : ?>
					<em class="comment-awaiting-moderation"><?php _e( 'Your comment is awaiting moderation.', 'newtheme' ); ?></em>
					<br />
				<?php endif; ?>

			</footer>

			<div class="comment-content"><?php comment_text(); ?></div>

			<div class="reply">
				<?php comment_reply_link( array_merge( $args, array( 'reply_text' => __( 'Reply <span>&darr;</span>', 'newtheme' ), 'depth' => $depth, 'max_depth' => $args['max_depth'] ) ) ); ?>
			</div><!-- .reply -->
		</article><!-- #comment-## -->

	<?php
			break;
	endswitch;
}
endif; // ends check for newtheme_comment()

[/codesyntax]

Esta función genera el código html necesario para mostrar cada comentario de un post.

[codesyntax lang=»php»]

<?php

if ( ! function_exists( 'newtheme_posted_on' ) ) :
/**
 * Prints HTML with meta information for the current post-date/time and author.
 * Create your own newtheme_posted_on to override in a child theme
 */
function newtheme_posted_on() {
	printf( __( '<span class="sep">Posted on </span><a href="%1$s" title="%2$s" rel="bookmark"><time class="entry-date" datetime="%3$s" pubdate>%4$s</time></a><span class="by-author"> <span class="sep"> by </span> <span class="author vcard"><a class="url fn n" href="%5$s" title="%6$s" rel="author">%7$s</a></span></span>', 'newtheme' ),
		esc_url( get_permalink() ),
		esc_attr( get_the_time() ),
		esc_attr( get_the_date( 'c' ) ),
		esc_html( get_the_date() ),
		esc_url( get_author_posts_url( get_the_author_meta( 'ID' ) ) ),
		esc_attr( sprintf( __( 'View all posts by %s', 'newtheme' ), get_the_author() ) ),
		get_the_author()
	);
}
endif;

[/codesyntax]

Esta función devuelve los metadatos de un post.

[codesyntax lang=»php»]

<?php

/**
 * Adds two classes to the array of body classes.
 * The first is if the site has only had one author with published posts.
 * The second is if a singular post being displayed
 */
function newtheme_body_classes( $classes ) {

	if ( function_exists( 'is_multi_author' ) && ! is_multi_author() )
		$classes[] = 'single-author';

	if ( is_singular() && ! is_home() && ! is_page_template( 'showcase.php' ) && ! is_page_template( 'sidebar-page.php' ) )
		$classes[] = 'singular';

	return $classes;
}
add_filter( 'body_class', 'newtheme_body_classes' );

[/codesyntax]

Esta función devuelve las clases de estilos que corresponden para la etiqueta body dependiendo del tipo de página que se muestre al usuario.

Logo Cassandra

Cassandra 1.x y PHP para desarrolladores SQL: PHPCassa (I)

0

¡Por fin llego el día! ¡Hoy toca programar!

Para ello vamos a utilizar las clases de abstracción de la base de datos PHPCassa que nos ahorrará bastante tiempo para trabajar con Cassandra. Puedes descargarlo desde https://github.com/thobbs/phpcassa.

Ubicamos PHPCassa en una carpeta dentro de nuestro servidor web y creamos dos archivos. Yo los he llamado test.php y cassandra.php. El segundo será una clase que nos ahorrará algunas lineas de código con las tareas habituales. El primero lo utilizaré para testear la clase y sus respectivos métodos.

Bien empecemos.

 

PRIMEROS PASOS

En primer lugar necesitamos incluir un archivo de PHPCassa en cassandra.php:

[codesyntax lang=»php»]

<?php

// CLASES NECESARIAS PARA CONECTAR CON CASSANDRA
require_once('phpcassa/lib/autoload.php');

[/codesyntax]

He inmediatamente llamamos a los namespace mínimos para trabajar con PHPCassa:

[codesyntax lang=»php»]

<?php

use phpcassa\Connection\ConnectionPool;
use phpcassa\ColumnFamily;
use phpcassa\SystemManager;
use phpcassa\Schema\StrategyClass;

[/codesyntax]

 

Justo debajo creamos la clase:

[codesyntax lang=»php»]

<?php

class cassandra {

}

[/codesyntax]

 

CONECTANDO

Para realizar la conexión a la BD, PHPCassa nos pide tan solo un dato obligatorio: el nombre del keyspace con el que vamos a trabajar. También nos permite añadir las ips de los nodos con los que queramos trabajar, aunque por defecto su valor es localhost. Por tanto podemos crear un constructor como el siguiente:

[codesyntax lang=»php»]

<?php

  function __construct($keyspace, $nodos = array('localhost')){
    if (!empty($keyspace)){
      $this->conexion = new ConnectionPool($keyspace, $nodos);
    }else{
      print "El keyspace está vacío";
    }
  }

[/codesyntax]

Este constructor nos permite indicarle a la clase el keyspace con el que queremos trabajar y la ip o nombre de servidor donde se encuentre nuestra instancia de Cassandra. Por defecto el puerto al que se va a conectar es el 9160. Si hubieses configurado Cassandra para escuchar en otro puerto deberás especificarlo: localhost:9160.

Este código nos crea una variable llamada conexion que será una instancia del objeto ConnectionPool, necesario para todas las consultas a la BD

 

GUARDANDO REGISTROS

Ahora procedemos a crear el método que guardará los registros. Para ello primero crearemos un objeto ColumnFamily al que le pasaremos el nombre de la column family en la que queremos trabajar:

[codesyntax lang=»php»]

<?php

  public function guardar($name_columnFamily, $key, $data = array()){
    try {
      $column_family = new ColumnFamily($this->conexion, $name_columnFamily);
      $column_family->insert($key, $data);
      return true;
    }catch(Exception $e){
     return false;
    }
  }

[/codesyntax]

Este método nos devolverá true si se ha guardado correctamente el registro, o false en caso de error.
Como puedes ver, al objeto ColumnFamily se le pasa como primer parámetro el objeto ConnectionPool que creamos en el constructor, después se le pasa el nombre de la column family.
Una vez creado el objeto ColumnFamily ya podemos utilizar el método insert para guardar el registro pasándole como parámetros la key y un array con las columnas y sus respectivos valores.

 

RECUPERANDO REGISTROS

Recuperar registros de Cassandra es algo más complejo que guardarlos:

Primero debemos añadir un nuevo namespace que nos permitirá usar una clase que nos será muy útil. El listado de namespaces nos quedaría así:

[codesyntax lang=»php» highlight_lines=»5″]

<?php

use phpcassa\Connection\ConnectionPool;
use phpcassa\ColumnFamily;
use phpcassa\ColumnSlice;
use phpcassa\SystemManager;
use phpcassa\Schema\StrategyClass;

[/codesyntax]

A continuación creamos el método en nuestro archivo cassandra.php:

 

[codesyntax lang=»php»]

<?php

  public function obtener($name_columnFamily, $key, $column_names= NULL, $range_start = "", $range_end = "", $column_count = 100, $invertir_orden=false){

    try{
      $column_slices = new ColumnSlice($range_start, $range_end, $column_count, $invertir_orden);
      $column_family = new ColumnFamily($this->conexion, $name_columnFamily);
      $result = $column_family->get($key, $column_slices, $column_names);
    }catch(Exception $e){
      return false;
    }

    return $result;

  }

[/codesyntax]

 

Este método tiene algunos parámetros más que al guardar, pero tienen su razón de ser:

$columnFamily: Nombre de la column family donde buscar.
$key: Clave del registro donde buscar.
$columns: Columnas a buscar. No es obligatorio. Por defecto NULL.
$range_start: Key por la que Cassandra debe empezar a recuperar registros. No es obligatorio. Por defecto «».$range_end: Key por la que Cassandra dejará de recuperar registros. No es obligatorio. Por defecto «».
$column_count: Número de registros a obtener, Por defecto 100.
$invertir_orden: Invierte el orden en el que se recuperar los registros. De mayor a menor o viceversa, de la A-Z o viceversa, etc.

Como ves tienes bastantes opciones para recuperar registros. Este método devuelve un array con los registros.

 

PROBANDO LA CLASE

Vamos a probar el código a ver que tal funciona. Nos vamos al archivo test.php y escribimos el siguiente código:

[codesyntax lang=»php»]

<?php

include_once "cassandra.php";

$cass = new cassandra('my_keyspace', array('192.168.1.10'));

$data = array(
    'nombre' => 'pepito',
    'ciudad' => 'Madrid',
    'vehiculo' => 'coche',
);

if ( $cass->guardar('my_column_family_standard', $key=1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', $key=1);

print_r($result);
?>

[/codesyntax]

Explico un poco el código anterior:

  1. Incluimos la clase en el archivo.
  2. Creamos el objeto indicándole el keyspace con el que trabajar (my_keyspace), y dentro de un array, la ip donde se encuentra en nodo de Cassandra. Si tuvieses Cassandra instalado en localhost no sería necesario indicar el segundo parámetro.
  3. Creamos el array que contendrá los datos a guardar.
  4. Creamos un condicional que guardará los datos en Cassandra y nos indicará si se han guardado correctamente o ha habido algún error.
  5. Guardamos en una variable ($result) los registros que recuperamos a través del método obtener del objeto $cass. A este método le indicamos la column family a buscar y la key a obtener.
  6. Mostramos los registros.

Si todo ha salido correctamente verás un texto como el siguiente cuando ejecutes el script:

El registro se ha guardado correctamente
 Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche )

Si te aparecen más registros es posible que no vaciases las column family con la que trabajas. Simplemente ves a Cassandra Cluster Admin, entra en la column family y pulsa en Truncate Column Family. Así eliminarás todos los datos de la column family.

 

ACTUALIZAR UN REGISTRO

Ahora que ya funciona nuestra clase podemos ampliarla con nuevas características.
Aunque pienses que para actualizar un registro es necesario un nuevo método, en Cassandra no es necesario, simplemente utilizaremos el método guardar indicandole la key a modificar y el array con los datos a guardar.

Justo debajo del código que ya tenemos en el archivo test.php escribimos lo siguiente:

[codesyntax lang=»php»]

<?php

$data = array(
    'ciudad' => 'Barcelona',
);

if ( $cass->guardar('my_column_family_standard', $key=1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', $key=1);

print_r($result);

[/codesyntax]

Como observarás el array no tiene todos los datos de la key que vamos a modificar, ya que no es necesario, tan solo pasaremos los datos que queremos actualizar. El resultado de este código es el siguiente:

El registro se ha guardado correctamente
 Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche )
 El registro se ha guardado correctamente
 Array ( [ciudad] => Barcelona [nombre] => pepito [vehiculo] => coche )

La columna ciudad a cambiado, el resto sigue igual, la razón está en que cuando le pasas a Cassandra una key que ya existe, lo que hace es actualizar las columnas que se correspondan con las keys del array. Si en ese array hubiera keys que no existen como columnas en el registro, Cassandra simplemente las crearía nuevas.

 

GUARDANDO UNA SUPER COLUMN

Aquí tampoco nos hace falta crear un nuevo método ya que nos sirve perfectamente el método guardar, pero deberemos hacerle algunas modificaciones.

En primer lugar, para trabajar con column families super es necesario añadir una llamada al namespace concreto. La lista de namespaces quedaría de la siguiente manera:

[codesyntax lang=»php» highlight_lines=»5″]

<?php

use phpcassa\Connection\ConnectionPool;
use phpcassa\ColumnFamily;
use phpcassa\SuperColumnFamily;
use phpcassa\ColumnSlice;
use phpcassa\SystemManager;
use phpcassa\Schema\StrategyClass;

[/codesyntax]

Ahora debemos modificar el método guardar y añadirle el parámetro $is_super_column, que nos permitirá crear un objeto SuperColumnFamily o ColumnFamily según corresponda. El método nos quedaría así:

[codesyntax lang=»php»]

<?php

  public function guardar($name_columnFamily, $key, $data = array(), $is_super_column = false){

    try {
      if ($is_super_column){
        $column_family = new SuperColumnFamily($this->conexion, $name_columnFamily);
      }
      else{
        $column_family = new ColumnFamily($this->conexion, $name_columnFamily);        
      }

      $column_family->insert($key, $data);
      return true;
    }catch(Exception $e){
     return false; 
    }
  }

[/codesyntax]

Como ambas clases comparten el método insert no nos hace falta incluir esa linea dentro del condicional.

A continuación modificamos el método obtener con el mismo parámetro y utilizando el mismo sistema para crear el objeto correspondiente:

[codesyntax lang=»php»]

<?php

  public function obtener($name_columnFamily, $key, $is_super_column=false, $column_names= NULL, $range_start = "", $range_end = "", $column_count = 100, $invertir_orden=false){

    try{
      if ($is_super_column){
        $column_family = new SuperColumnFamily($this->conexion, $name_columnFamily);
      }
      else{
        $column_family = new ColumnFamily($this->conexion, $name_columnFamily);        
      }
      $column_slices = new ColumnSlice($range_start, $range_end, $column_count, $invertir_orden);
      $result = $column_family->get($key, $column_slices, $column_names);
    }catch(Exception $e){
      return false;
    }

    return $result;

  }

[/codesyntax]

Ahora podemos añadir el siguiente código a nuestro archivo test.php:

[codesyntax lang=»php»]

<?php

$data = array('vecino_1' => array(
    'nombre' => 'pepito',
    'ciudad' => 'Madrid',
    'vehiculo' => 'coche',
));

if ( $cass->guardar('my_column_family_super', $key=1, $data, $is_super_column=true)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_super', $key=1, $is_super_column=true);

print_r($result);

[/codesyntax]

El único cambio además del nombre de la column family donde vamos a guardar el registro, se encuentra en el array con los datos. Este tiene un elemento que es la key de la super column, y como valor, el array de las columns a guardar.

Si ejecutamos el código anterior nos devolverá lo siguiente:

El registro se ha guardado correctamente
 Array ( [vecino_1] => Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche ) )

[ci-box type=»warning»]Al probar el código, PHP me devolvió el siguiente aviso:
Strict Standards: Declaration of phpcassa\SuperColumnFamily::add() should be compatible with that of phpcassa\ColumnFamily::add() in /var/www/prueba_cassandra/phpcassa/lib/phpcassa/SuperColumnFamily.php on line 491. 

No te preocupes no afecta ni a los ejemplos ni a la clase que funcionan correctamente.[/ci-box]

ACTUALIZANDO UNA SUPER COLUMN

La actualización de una super column se limita a las columnas que contienen los valores del registro no a su key. Si modificáramos la key , lo que en realidad estaríamos haciendo sería crear una nueva super column. Añadimos el siguiente código a nuestro archivo test.php:

[codesyntax lang=»php»]

<?php

$data = array('vecino_1' => array(
    'nombre' => 'pepito',
    'ciudad' => 'Barcelona',
    'vehiculo' => 'coche',
));

if ( $cass->guardar('my_column_family_super', $key1, $data, $is_super_column=true)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_super', $key=1, $is_super_column=true);

print_r($result);

[/codesyntax]

Y el resultado es:

El registro se ha guardado correctamente
 Array ( [vecino_1] => Array ( [ciudad] => Barcelona [nombre] => pepito [vehiculo] => coche ) )

 

ELIMINAR REGISTROS

Sí, aquí toca crear un nuevo método para nuestra clase en cassandra.php, aunque tampoco nos vamos a matar programando:

 

[codesyntax lang=»php»]

<?php

  public function eliminar($name_columnFamily, $key, $is_super_column = false){

    try{
      if ($is_super_column){
        $column_family = new SuperColumnFamily($this->conexion, $name_columnFamily);
      }
      else{
        $column_family = new ColumnFamily($this->conexion, $name_columnFamily);
      }
      $column_family->remove($key);    
      return true;
    }catch(Exception $e){
      return false;
    }
  }

[/codesyntax]

 

El método es bastante sencillo: se le pasan tres parámetros que ya conocemos.

Dentro del método se crea un objeto ColumnFamily y se utiliza el método remove para eliminar el registro pasándole la key correspondiente, y si fuese una super column, la key de este.
El método remove tiene un segundo parámetro que por defecto tiene un valor null, en él se pueden añadir como array los nombres de las columnas a eliminar. Como no es habitual ese proceso he creído adecuado no utilizarlo.

Una vez añadido esté método a nuestra clase modificamos el archivo test.php con el siguiente código:

[codesyntax lang=»php»]

<?php

if ( $cass->eliminar('my_column_family_standard', $key=1)){
  print "El registro se ha eliminado correctamente<br />";
}else{
  print "Error al eliminar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', $key=1);

print_r($result);

[/codesyntax]

Y el resultado es:

El registro se ha eliminado correctamente

 

De momento con esto es suficiente, dejo en tus manos estos métodos para que juegues con ellos todo lo que quieras y te familiarices con PHPCassa.

En el próximo post trataré las Counter Columns que nos servirán para contar registros, los Secondary Index que nos permitirán realizar búsquedas por columnas concretas, y algunas cosas más.

Logo Cassandra

Cassandra 1.x y PHP para desarrolladores SQL: Cassandra Cluster Admin, el phpMyAdmin de Cassandra

3

En el anterior post expliqué el funcionamiento de la consola de Cassandra y como trabajar con ella. En este post explicaré como hacer lo mismo de una forma más rápida y fácil.

La razón de que no haya empezado ha explicar como se utiliza Cassandra desde PHP, es que primero hay que conocer cómo funciona Cassandra, su modelo de datos (que ya hemos visto) y algunos comandos básicos para ir aprendiendo a guardar y recuperar datos. El próximo post ya trataré el funcionamiento de PHPCassa y empezaremos a programar.

Este post será bastante ligerito. Explicaré principalmente como hacer lo mismo que hicimos por consola pero de modo gráfico. CassAdmin, como yo le llamo, tiene más opciones de edición para los keyspaces y column families de los que vamos a ver (igual que ocurría con la consola), pero solo tocaremos las opciones más habituales.

 

INSTALACIÓN

Lo típico en estos casos. Descargar. Descomprimir y ejecutar. Descargamos los archivos desde el repositorio de git: https://github.com/sebgiroux/Cassandra-Cluster-Admin, o a través de git o como archivo comprimido. Como más te guste.

Proceso para descargar Cassandra Cluster Admin

Página de descargas del administrador

Ahora descomprimimos a una carpeta dentro de nuestro servidor web, ya que trabajamos con una aplicación programada en PHP.

Si tienes Cassandra instalado en otro equipo que no sea en local, una máquina virtual por ejemplo, tendrás que cambiar la ip a la que se conecta cassAdmin. Es bastante sencillo. Para ello debes modificar el archivo includes/config.inc.php y sustituir la ip de localhost (127.0.0.1)  por la ip del equipo en el que tengas instalado Cassandra:

Archivo config.inc.php

Como verás en la captura, yo utilizo la ip local 192.168.1.10 que pertenece a una máquina virtual. Si tuviera instalado Cassandra en  el mismo equipo la ip a la que debería apuntar sería 127.0.0.1. El puerto no lo modificamos.

Una vez instalado y configurado (si fuese el caso) probamos a acceder desde nuestro navegador. Debería mostrarte algo como esto:

Página principal de Cassandra Cluster Admin

CREAR KEYSPACES

Como has podido ver, en la página principal del administrador ya aparece un keyspace, llamado system, perteneciente a Cassandra, con lo que lo mantendremos como está.

Justo encima tenemos un botón para crear un nuevo keyspace (Create a new keyspace). Lo pulsamos.

Formulario para crear un keyspace

Solo nos pide tres parámetros a rellenar:


Keyspace name
: El nombre del keyspace a crear.
Replication factor: Es el número de servidores o instancias de Cassandra de los que se debe guardar un registro u obtener una respuesta al recuperar algún registro.
Strategy: Es la estrategia que seguirá Cassandra para guardar los datos. En el caso de tener varios servidores o centro de datos diferenciados entre sí, se aplicará una estrategia u otra para que los datos no se pierdan. Más info: http://answers.oreilly.com/topic/2408-replica-placement-strategies-when-using-cassandra/ 

En nuestro caso escribiremos los siguientes valores:

Formulario para crear un keyspace con datos

Pulsamos en Create keyspace y nos llevará a la página principal:

Página principal mostrando el keyspace que acabamos de crear

Pulsamos sobre el keyspace que acabamos de crear y nos llevará a la siguiente página:

Página de detalle del keyspace my_keyspace

Aquí podemos ver información relativa al keyspace y al anillo (o cluster) en el que se encuentra guardado. También nos permite editar el keyspace o eliminarlo, pero la opción más interesante es la de crear nuevas column families (Create a new column family).

 

CREAR UNA COLUMN FAMILY

Dentro del keyspace pulsamos sobre el botón Create a new column family, nos mostrará lo siguiente:

Formulario para crear una column family

 

Primero crearemos una column family standard con los siguientes datos:

Datos para crear la primera column family

Para crear una column family solo son necesarios tres parámetros:


Column Family Name
: El nombre de la column family que vamos a crear.
Column Type: El tipo de column family que vamos a crear (Standard o Super).
Comparator Type: El comparador principal de las columnas. Es decir, la codificación que tendrán los datos dentro de la column family.

Pulsamos en Create Column Family y en la página de nuestro keyspace se habrá añadido una nueva column family:

Detalle de la column family creada

 

AÑADIR REGISTROS A UNA COLUMN FAMILY STANDARD

Ahora toca guardar registros en la BD.
Como comenté en post anteriores Cassandra no necesita conocer los campos de las tablas (nuestras column families) ya que los creamos cada vez que añadimos un registro.

Primero en la página principal del keyspace haz click en el nombre de la column family. Te aparecerá lo siguiente:

 

Detalle de la página principal de la column family creada

En esta página te aparecerá, además de la información referente a la column family, los siguientes botones:


Browse Data
: Para mostrar un listado de los registros que contiene la column family.
Create Secondary Index: Para crear indices secundarios. Parecido a los indices de MySQL.
Get Key: Para buscar una clave o registro concreto.
Insert Row: Para insertar un nuevo registro.
Edit Column Family: Para editar los parámetros de la column family.
Truncate Column Family: Para eliminar los registros de la column family sin eliminar esta.
Drop Column Family: Para eliminar la column family y su contenido.

Pulsamos en Insert Row. Nos aparecerá lo siguiente:

Formulario para insertar registros

Siempre que añadamos un nuevo registro deberemos indicar una key diferente que deberá ser única, sino cassAdmin pensará que lo que quieres hacer es actualizar ese registro. Añadimos los siguientes datos al formulario:

Formulario para insertar registros con datos

 

Para añadir otra fila de cuadro de texto solo tienes que pulsar el botón Add…
Volvemos a la página principal de la column family y pulsamos en Browse Data. Aquí veremos un listado con los registros que hayamos añadido:

 

Listado de registros

 

CREAR UNA COLUMN FAMILY SUPER Y AÑADIR REGISTROS

El proceso para crear una column family Super es idéntico a las column family Standard, solo hay que cambiar un valor a la hora de crearla:

Creación de una column family Super

Entramos en la página principal de la nueva column family y pulsamos en Insert Row. Aquí veremos que el formulario a cambiado un poco, nos aparece un nuevo campo llamado Super Column Name y un nuevo botón encima del formulario, Add Super Column:

Formulario para insertar registros de una column family super

Las column family Super son como las muñecas matrioskas, esas figuras que si las abrías había otra igual dentro, y dentro de esa otra más, y otra, etc. Algo parecido sucede con estas column family. Disponemos de una key (nuestra primera matrioska) que contiene a las super columns (segunda matrioska), que a su vez contienen las columnas clave:valor.

Añadamos un registro para verlo:

Datos para crear una super column

Si nos vamos a Browse Data:

Listado de registros en una column family Super

Como ves, ahora las columns se agruparían dentro de la super column. Añadiré más registros para que lo veas mejor:

Listado de registros en una column family Super

¿Ves? Las keys agrupan a las super columns y estas a su vez a las columns.

 

Creo que esto es suficiente para que conozcas el funcionamiento de Cassandra Cluster Admin. Quedarían algunas cosillas, como editar registros, hacer búsquedas o eliminar registros, pero eso es bastante sencillo (a excepción de las Secondary Index y las Counter Columns que trataré más adelante).

Para cualquier duda o problema déjala en los comentarios.

Logo Cassandra

Cassandra y PHP para desarrolladores SQL: PHPCassa (I)

10

¡Por fin llego el día! ¡Hoy toca programar!

Para ello vamos a utilizar el cliente de alto nivel PHPCassa que nos ahorrará bastante tiempo para trabajar con Cassandra. Puedes descargarlo desde https://github.com/thobbs/phpcassa.

Ubicamos phpCassa en una carpeta dentro de nuestro servidor web y creamos dos archivos. Yo los he llamado test.php y cassandra.php, El segundo será una clase que nos ahorrará algunas lineas de código con las tareas habituales. El primero lo utilizaré para testear la clase y sus respectivos métodos.

Bien empecemos.

 

PRIMEROS PASOS

En primer lugar necesitamos incluir dos archivos de phpCassa en cassandra.php:

[codesyntax lang=»php»]

<?php

// CLASES NECESARIAS PARA CONECTAR CON CASSANDRA
require_once('phpcassa/connection.php');
require_once('phpcassa/columnfamily.php');

[/codesyntax]

El primero de ellos dispone de los métodos para conectar con Cassandra a través de Thirft; el segundo tiene los métodos para trabajar con las column families.

Justo debajo creamos la clase:

[codesyntax lang=»php»]

<?php

class cassandra {

}

[/codesyntax]

 

CONECTANDO

Para realizar la conexión a la BD, phpCassa nos pide tan solo un dato obligatorio: el nombre del keyspace con el que vamos a trabajar. También nos permite añadir las ips de los nodos con los que queramos trabajar, aunque por defecto su valor es localhost. Por tanto podemos crear un constructor como el siguiente:

[codesyntax lang=»php»]

<?php

  function __construct($keyspace, $nodos = array('localhost')){
    if (!empty($keyspace)){
      $this->conexion = new ConnectionPool($keyspace, $nodos);
    }else{
      print "El keyspace está vacío";
    }
  }

[/codesyntax]

Este constructor nos permite indicarle a la clase el keyspace con el que queremos trabajar y la ip o nombre de servidor donde se encuentre nuestra instancia de Cassandra. Por defecto el puerto al que se va a conectar es el 9160. Si hubieses configurado Cassandra para escuchar en otro puerto deberás especificarlo: localhost:9160.

Este código nos crea una variable llamada conexion que contendrá el objeto ConnectionPool, necesario para todas las consultas a la BD

 

GUARDANDO REGISTROS

Ahora procedemos a crear el método que guardará los registros. Para ello primero crearemos un objeto ColumnFamily al que le pasaremos el nombre de la column family en la que queremos trabajar:

[codesyntax lang=»php»]

<?php

  public function guardar($columnFamily, $key, $data = array()){
    try {
      $column_family = new ColumnFamily($this->conexion, $columnFamily);
      $column_family->insert($key, $data);
      return true;
    }catch(Exception $e){
     return false;
    }
  }

[/codesyntax]

Este método nos devolverá true si se ha guardado correctamente el registro, o false en caso de error.
Como puedes ver, al objeto ColumnFamily se le pasa como primer parámetro el objeto ConnectionPool que creamos en el constructor, después se le pasa el nombre de la column family.
Una vez creado el objeto ColumnFamily ya podemos utilizar el método insert para guardar el registro pasándole como parámetros la key y un array con las columnas y sus respectivos valores.

 

RECUPERANDO REGISTROS

Recuperar registros de Cassandra es algo más complejo que guardarlos:

[codesyntax lang=»php»]

<?php

  public function obtener($columnFamily, $key, $super_column=NULL, $columns= NULL, $range_start = "", $column_count = 100, $invertir_orden=false){

      try{
          $column_family = new ColumnFamily($this->conexion, $columnFamily);
          $result = $column_family->get($key, $columns, $range_start, "", $invertir_orden, $column_count, $super_column);
      }catch(Exception $e){
          return false;
      }

      return $result;

  }

[/codesyntax]

Este método tiene algunos parámetros más que al guardar, pero tienen su razón de ser:

$columnFamily: Nombre de la column family donde buscar.
$key: Clave del registro donde buscar.
$super_column: Key o clave de la super column que se debe buscar. No es obligatorio. Por defecto NULL.
$columns: Columnas a buscar. No es obligatorio. Por defecto NULL.
$range_start: Key por la que Cassandra debe empezar a recuperar registros. No es obligatorio. Por defecto «».
$column_count: Número de registros a obtener, Por defecto 100.
$invertir_orden: Invierte el orden en el que se recuperar los registros. De mayor a menor o viceversa, de la A-Z o viceversa, etc.

Como ves tienes bastantes opciones para recuperar registros. Este método devuelve un array con los registros.

 

PROBANDO LA CLASE

Vamos a probar el código a ver que tal funciona. Nos vamos al archivo test.php y escribimos el siguiente código:

[codesyntax lang=»php»]

<?php

include_once "cassandra.php";

$cass = new cassandra('my_keyspace', array('192.168.1.10'));

$data = array(
    'nombre' => 'pepito',
    'ciudad' => 'Madrid',
    'vehiculo' => 'coche',
);

if ( $cass->guardar('my_column_family_standard', 1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', 1);

print_r($result);
?>

[/codesyntax]

Explico un poco el código anterior:

  1. Incluimos la clase en el archivo.
  2. Creamos el objeto indicándole el keyspace con el que trabajar (my_keyspace), y dentro de un array, la ip donde se encuentra en nodo de Cassandra. Si tuvieses Cassandra instalado en localhost no sería necesario indicar el segundo parámetro.
  3. Creamos el array que contendrá los datos a guardar.
  4. Creamos un condicional que guardará los datos en Cassandra y nos indicará si se han guardado correctamente o ha habido algún error.
  5. Guardamos en una variable ($result) los registros que recuperamos a través del método obtener del objeto $cass. A este método le indicamos la column family a buscar y la key a obtener.
  6. Mostramos los registros.

Si todo ha salido correctamente verás un texto como el siguiente cuando ejecutes el script:

El registro se ha guardado correctamente
Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche )

Si te aparecen más registros es posible que no vaciases las column family con la que trabajas. Simplemente ves a cassAdmin, entra en la column family y pulsa en Truncate Column Family. Así eliminarás todos los datos de la column family.

 

ACTUALIZAR UN REGISTRO

Ahora que ya funciona nuestra clase podemos ampliarla con nuevas características.
Aunque pienses que para actualizar un registro es necesario un nuevo método, en Cassandra no es necesario, simplemente utilizaremos el método guardar indicandole la key a modificar y el array con los datos a guardar.

Justo debajo del código que ya tenemos en el archivo test.php escribimos lo siguiente:

[codesyntax lang=»php»]

<?php

$data = array(
    'ciudad' => 'Barcelona',
);

if ( $cass->guardar('my_column_family_standard', 1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', 1);

print_r($result);

[/codesyntax]

Como observarás el array no tiene todos los datos de la key que vamos a modificar, ya que no es necesario, tan solo pasaremos los datos que queremos actualizar. El resultado de este código es el siguiente:

El registro se ha guardado correctamente
Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche )
El registro se ha guardado correctamente
Array ( [ciudad] => Barcelona [nombre] => pepito [vehiculo] => coche )

La columna ciudad a cambiado, el resto sigue igual, la razón está en que cuando le pasas a Cassandra una key que ya existe, lo que hace es actualizar las columnas que se correspondan con las keys del array. Si en ese array hubiera keys que no existen como columnas en el registro, Cassandra simplemente las crearía nuevas.

 

GUARDANDO UNA SUPER COLUMN

Aquí tampoco nos hace falta crear un nuevo método ya que nos sirve perfectamente el método guardar.

Añadimos el siguiente código a nuestro archivo test.php:

[codesyntax lang=»php»]

<?php

$data = array('vecino_1' => array(
    'nombre' => 'pepito',
    'ciudad' => 'Madrid',
    'vehiculo' => 'coche',
));

if ( $cass->guardar('my_column_family_super', 1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_super', 1);

print_r($result);

[/codesyntax]

El único cambio además del nombre de la column family donde vamos a guardar el registro, se encuentra en el array con los datos. Este tiene un elemento que es la key de la super column, y como valor, el array de las columns a guardar.

Si ejecutamos el código anterior nos devolverá lo siguiente:

El registro se ha guardado correctamente
Array ( [vecino_1] => Array ( [ciudad] => Madrid [nombre] => pepito [vehiculo] => coche ) )

 

ACTUALIZANDO UN SUPER COLUMN

La actualización de una super column se limita a las columnas que contienen los valores del registro no a su key. Si modificáramos la key , lo que en realidad estaríamos haciendo sería crear una nueva super column. Añadimos el siguiente código a nuestro archivo test.php:

[codesyntax lang=»php»]

<?php

$data = array('vecino_1' => array(
    'nombre' => 'pepito',
    'ciudad' => 'Barcelona',
    'vehiculo' => 'coche',
));

if ( $cass->guardar('my_column_family_super', 1, $data)){
  print "El registro se ha guardado correctamente<br />";
}else{
  print "Error al guardar el registro<br />";
}

$result = $cass->obtener('my_column_family_super', 1);

print_r($result);

[/codesyntax]

Y el resultado es:

El registro se ha guardado correctamente
Array ( [vecino_1] => Array ( [ciudad] => Barcelona [nombre] => pepito [vehiculo] => coche ) )

 

ELIMINAR REGISTROS

Sí, aquí toca crear un nuevo método para nuestra clase en cassandra.php, aunque tampoco nos vamos a matar programando:

[codesyntax lang=»php»]

<?php

  public function eliminar($columnFamily, $key, $super_column = null){

    try{
      $column_family = new ColumnFamily($this->conexion, $columnFamily);
      $column_family->remove($key, null, $super_column);
      return true;
    }catch(Exception $e){
      return false;
    }
  }

[/codesyntax]

El método es bastante sencillo: se le pasan tres parámetros que ya conocemos.

Dentro del método se crea un objeto ColumnFamily y se utiliza el método remove para eliminar el registro pasándole la key correspondiente, y si fuese una super column, la key de este.
Observarás que el segundo parámetro del método remove tiene un valor null, en él se pueden añadir como array los nombres de las columnas a eliminar. Como no es habitual ese proceso he creído adecuado dejarlo como null.

Una vez añadido esté método a nuestra clase modificamos el archivo test.php con el siguiente código:

[codesyntax lang=»php»]

<?php

if ( $cass->eliminar('my_column_family_standard', 1)){
  print "El registro se ha eliminado correctamente<br />";
}else{
  print "Error al eliminar el registro<br />";
}

$result = $cass->obtener('my_column_family_standard', 1);

print_r($result);

[/codesyntax]

Y el resultado es:

El registro se ha eliminado correctamente

 

De momento con esto es suficiente, dejo en tus manos estos métodos para que juegues con ellos todo lo que quieras y te familiarices con phpCassa.

En el próximo post trataré las Counter Columns que nos servirán para contar registros, los Secondary Index que nos permitirán realizar búsquedas por columnas concretas, y algunas cosas más.

Logo Cassandra

Cassandra y PHP para desarrolladores SQL: Cassandra Cluster Admin, el phpMyAdmin de Cassandra

4

En el anterior post expliqué el funcionamiento de la consola de Cassandra y como trabajar con ella. En este post explicaré como hacer lo mismo de una forma más rápida y fácil.

La razón de que no haya empezado ha explicar como se utiliza Cassandra desde PHP, es que primero hay que conocer cómo funciona Cassandra, su modelo de datos (que ya hemos visto) y algunos comandos básicos para ir aprendiendo a guardar y recuperar datos. El próximo post ya trataré el funcionamiento de phpCassa y empezaremos a programar.

Este post será bastante ligerito. Explicaré principalmente como hacer lo mismo que hicimos por consola pero de modo gráfico. CassAdmin, como yo le llamo, tiene más opciones de edición para los keyspaces y column families de los que vamos a ver (igual que ocurría con la consola), pero solo tocaremos las opciones más habituales.

 

INSTALACIÓN

Lo típico en estos casos. Descargar. Descomprimir y ejecutar. Descargamos los archivos desde el repositorio de git: https://github.com/sebgiroux/Cassandra-Cluster-Admin, o a través de git o como archivo comprimido. Como más te guste.

Repositorio de Cassandra Cluster Admin

Página de descargas del administrador

Ahora descomprimimos a una carpeta dentro de nuestro servidor web, ya que trabajamos con una aplicación programada en PHP.

Si tienes Cassandra instalado en otro equipo que no sea en local, una máquina virtual por ejemplo, tendrás que cambiar la ip a la que se conecta cassAdmin. Es bastante sencillo. Para ello debes modificar el archivo includes/config.inc.php y sustituir la ip de localhost (127.0.0.1)  por la ip del equipo en el que tengas instalado Cassandra:

Archivo config.inc.php

Como verás en la captura, yo utilizo la ip local 192.168.1.10 que pertenece a una máquina virtual. Si tuviera instalado Cassandra en  el mismo equipo la ip a la que debería apuntar sería 127.0.0.1. El puerto no lo modificamos.

Una vez instalado y configurado (si fuese el caso) probamos a acceder desde nuestro navegador. Debería mostrarte algo como esto:

Página principal de Cassandra Cluster Admin

CREAR KEYSPACES

Como has podido ver, en la página principal del administrador ya aparece un keyspace, llamado system, perteneciente a Cassandra, con lo que lo mantendremos como está.

Justo encima tenemos un botón para crear un nuevo keyspace (Create a new keyspace). Lo pulsamos.

Formulario para crear un keyspace

Solo nos pide tres parámetros a rellenar:


Keyspace name
: El nombre del keyspace a crear.
Replication factor: Es el número de servidores o instancias de Cassandra de los que se debe guardar un registro u obtener una respuesta al recuperar algún registro.
Strategy: Es la estrategia que seguirá Cassandra para guardar los datos. En el caso de tener varios servidores o centro de datos diferenciados entre sí, se aplicará una estrategia u otra para que los datos no se pierdan. Más info: http://answers.oreilly.com/topic/2408-replica-placement-strategies-when-using-cassandra/ 

En nuestro caso escribiremos los siguientes valores:

Formulario para crear un keyspace con datos

Pulsamos en Create keyspace y nos llevará a la página principal:

Página principal mostrando el keyspace que acabamos de crear

Pulsamos sobre el keyspace que acabamos de crear y nos llevará a la siguiente página:

Página de detalle del keyspace my_keyspace

Aquí podemos ver información relativa al keyspace y al anillo (o cluster) en el que se encuentra guardado. También nos permite editar el keyspace o eliminarlo, pero la opción más interesante es la de crear nuevas column families (Create a new column family).

 

CREAR UNA COLUMN FAMILY

Dentro del keyspace pulsamos sobre el botón Create a new column family, nos mostrará lo siguiente:

Formulario para crear una column family

 

Primero crearemos una column family standard con los siguientes datos:

Datos para crear la primera column family

Para crear una column family solo son necesarios tres parámetros:


Column Family Name
: El nombre de la column family que vamos a crear.
Column Type: El tipo de column family que vamos a crear (Standard o Super).
Comparator Type: El comparador principal de las columnas. Es decir, la codificación que tendrán los datos dentro de la column family.

Pulsamos en Create Column Family y en la página de nuestro keyspace se habrá añadido una nueva column family:

Detalle de la column family creada

 

AÑADIR REGISTROS A UNA COLUMN FAMILY STANDARD

Ahora toca guardar registros en la BD.
Como comenté en post anteriores Cassandra no necesita conocer los campos de las tablas (nuestras column families) ya que los creamos cada vez que añadimos un registro.

Primero en la página principal del keyspace haz click en el nombre de la column family. Te aparecerá lo siguiente:

 

Detalle de la página principal de la column family creada

En esta página te aparecerá, además de la información referente a la column family, los siguientes botones:


Browse Data
: Para mostrar un listado de los registros que contiene la column family.
Create Secondary Index: Para crear indices secundarios. Parecido a los indices de MySQL.
Get Key: Para buscar una clave o registro concreto.
Insert Row: Para insertar un nuevo registro.
Edit Column Family: Para editar los parámetros de la column family.
Truncate Column Family: Para eliminar los registros de la column family sin eliminar esta.
Drop Column Family: Para eliminar la column family y su contenido.

Pulsamos en Insert Row. Nos aparecerá lo siguiente:

Formulario para insertar registros

Siempre que añadamos un nuevo registro deberemos indicar una key diferente que deberá ser única, sino cassAdmin pensará que lo que quieres hacer es actualizar ese registro. Añadimos los siguientes datos al formulario:

Formulario para insertar registros con datos

 

Para añadir otra fila de cuadro de texto solo tienes que pulsar el botón Add…
Volvemos a la página principal de la column family y pulsamos en Browse Data. Aquí veremos un listado con los registros que hayamos añadido:

 

Listado de registros

 

CREAR UNA COLUMN FAMILY SUPER Y AÑADIR REGISTROS

El proceso para crear una column family Super es idéntico a las column family Standard, solo hay que cambiar un valor a la hora de crearla:

Creación de una column family Super

Entramos en la página principal de la nueva column family y pulsamos en Insert Row. Aquí veremos que el formulario a cambiado un poco, nos aparece un nuevo campo llamado Super Column Name y un nuevo botón encima del formulario, Add Super Column:

Formulario para insertar registros de una column family super

Las column family Super son como las muñecas matrioskas, esas figuras que si las abrías había otra igual dentro, y dentro de esa otra más, y otra, etc. Algo parecido sucede con estas column family. Disponemos de una key (nuestra primera matrioska) que contiene a las super columns (segunda matrioska), que a su vez contienen las columnas clave:valor.

Añadamos un registro para verlo:

Datos para crear una super column

Si nos vamos a Browse Data:

Listado de registros en una column family Super

Como ves, ahora las columns se agruparían dentro de la super column. Añadiré más registros para que lo veas mejor:

Listado de registros en una column family Super

¿Ves? Las keys agrupan a las super columns y estas a su vez a las columns.

 

Creo que esto es suficiente para que conozcas el funcionamiento de Cassandra Cluster Admin. Quedarían algunas cosillas, como editar registros, hacer búsquedas o eliminar registros, pero eso es bastante sencillo (a excepción de las Secondary Index y las Counter Columns que trataré más adelante).

Para cualquier duda o problema déjala en los comentarios.

Ir arriba