Organice su Próximo Proyecto PHP en la Forma Correcta

Spanish (Español) translation by Rodney Martinez (you can also view the original English article)

Cuando comienza con PHP, puede ser desalentador darse cuenta cuál es la mejor forma de organizar un proyecto. Si algunas vez ha estado confundido con respecto a dónde poner sus imágenes, bibliotecas externas, o conservar la información lógica separada de su composición, entonces revise estos consejos; ya que lo pondrán en la dirección correcta.

Detalles del Tutorial

Programa: PHP/Proyectos
Versión: 1
Dificultad: Fácil
Tiempo Estimado para la Realización: 20 mínutos

Estructura del Directorio

Me gustaría decir que la cosa número para poner su proyecto en funcionamiento rápidamente es tener una estructura de directorio sólida y que usted puede volver a usar para múltiples proyectos. Si usted está usando un framework, por lo general, éste ofrecerá una estructura para usarlo, pero en este escenario vamos a trabajar en un sitio web sencillo.

Desglose

Es muy probable que ya esté muy familiarizado con la estructura public_html. Esta es la Raíz del Documento en la cual todos sus archivos públicos pueden tener acceso (/public_html/page.php accede a example.com/page.php).
- img — Todos sus archivos de imágenes. He decidido dividir las imágenes de contenido de las imágenes del diseño.
- css — Todos sus archivos CSS.
- js — Todos sus archivos javascript.
El directorio resources deberá de contener todas las bibliotecas de terceros, bibliotecas personalizadas, archivos de configuración y cualquier otro código que actué como un recurso en su proyecto.
- config.php — El archivo de configuración principal. Deberá almacenar la configuración del sitio.
- library — Ubicación central para todos las bibliotecas personalizadas.
- templates — Componentes reusables que conforman su composición.

El Archivo de Configuración

Como diseñadores y desarrolladores, nuestro objetivo principal es hacer tan poco trabajo como sea posible. Un camino para alcanzar este objetivo es con los archivos config. Para tener una mejor idea de lo que un archivo de configuración deberá tener, entonces revise el siguiente ejemplo.

<?php

/*
  The important thing to realize is that the config file should be included in every
	page of your project, or at least any page you want access to these settings.
	This allows you to confidently use these settings throughout a project because
	if something changes such as your database credentials, or a path to a specific resource,
	you'll only need to update it here.
*/

$config = array(
	"db" => array(
		"db1" => array(
			"dbname" => "database1",
			"username" => "dbUser",
			"password" => "pa$$",
			"host" => "localhost"
		),
		"db2" => array(
			"dbname" => "database2",
			"username" => "dbUser",
			"password" => "pa$$",
			"host" => "localhost"
		)
	),
	"urls" => array(
		"baseUrl" => "http://example.com"
	),
	"paths" => array(
		"resources" => "/path/to/resources",
		"images" => array(
			"content" => $_SERVER["DOCUMENT_ROOT"] . "/images/content",
			"layout" => $_SERVER["DOCUMENT_ROOT"] . "/images/layout"
		)
	)
);

/*
	I will usually place the following in a bootstrap file or some type of environment
	setup file (code that is run at the start of every page request), but they work 
	just as well in your config file if it's in php (some alternatives to php are xml or ini files).
*/

/*
	Creating constants for heavily used paths makes things a lot easier.
	ex. require_once(LIBRARY_PATH . "Paginator.php")
*/
defined("LIBRARY_PATH")
	or define("LIBRARY_PATH", realpath(dirname(__FILE__) . '/library'));
	
defined("TEMPLATES_PATH")
	or define("TEMPLATES_PATH", realpath(dirname(__FILE__) . '/templates'));

/*
	Error reporting.
*/
ini_set("error_reporting", "true");
error_reporting(E_ALL|E_STRCT);

?>

Este es un archivo de configuración básico. Un arreglo múlti-dimensional sirve como una estructura flexible para acceder a varios objetos de config tales como las credenciales de la base de datos.

db — Almacena las credenciales de la base de datos u otros datos pertinentes para sus bases de datos.
paths — Frecuentemente usa rutas a varios recursos para su sitio.
- archivos de registro
- directorios para cargar archivos
- recursos
urls — Almacena las urls que pueden ser útiles cuando hacen referencia a recursos remotos a través de su sitio.
emails — Almacena la depuración o correos admin para usar cuando maneje errores o en formularios de contacto.

Usando constantes para rutas de uso común hace que incluir declaraciones (require o include) sea un soplo, y si la ruta alguna vez cambia, entonces usted solamente necesitará actualizarla en un lugar.

Usando diferentes Archivos de Configuración para Múltiples Ambientes

Al usar diferentes archivos de configuración para diferentes ambientes, usted puede tener configuraciones relevantes dependiendo del ambiente actual. Lo que significa que si usted usa diferentes credenciales de bases de datos o diferentes rutas para cada ambiente, al configurar los respectivos archivos de configuración, usted asegurará que su código funcione sin problemas cuando esté actualizando su sitio web en tiempo real. Esto también le permite tener diferentes configuraciones de reportes de error basado en el ambiente actual. ¡Nunca muestra errores en su sitio web en vivo! Mostrando errores en el sitio web en vivo podría exponer datos sensitivos a usuarios (tales como las contraseñas).

El diseño

Plantillas reusables son otro enorme ahorrador de tiempo. Hay algunas bibliotecas magníficas para las plantillas (tales como Smarty) y siempre animo a usar este tipo de biblioteca en lugar de reinventar la rueda. Estas bibliotecas ofrecen mucha funcionalidad (como los métodos auxiliares para formato de moneda y ofuscando direcciones de correo electrónico). Ya que esto es un sitio sencillo, sin embargo, no queremos ocupar el tiempo en configurar la biblioteca, sino que estaremos usando los conceptos más básicos de las plantillas básicas. Conseguiremos estos incluyendo secciones comunes o módulos para nuestras páginas del sitio, de esta manera, si queremos cambiar algo en el header, encabezado, como añadir un enlace a la navegación global, éste cambio será reproducido a través de todo el sitio web.

header.php

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Simple Site</title>
</head>

<body>
<div id="header">
	<h1>Simple Site</h1>
	<ul class="nav global">
		<li><a href="#">Home</a></li>
		<li><a href="#">Articles</a></li>
		<li><a href="#">Portfolio</a></li>
	</ul>

</div>

rightPanel.php

<div id="siteControls">
	<ul class="categories">
		<li>PHP</li>
		<li>HTML</li>
		<li>CSS</li>
	</ul>
	<div class="ads">
		<!-- ads code -->
	</div>

</div>

footer.php

<div id="footer">
	Footer content...
</div>
</body>
</html>

index.php

Digamos que elaboramos todos los componentes para nuestra composición (header, footer, rightPanel) en nuestro recurso de directorio debajo de plantillas.

<?php	
	// load up your config file
	require_once("/path/to/resources/config.php");
	
	require_once(TEMPLATES_PATH . "/header.php");
?>
<div id="container">
	<div id="content">
		<!-- content -->
	</div>
	<?php
		require_once(TEMPLATES_PATH . "/rightPanel.php");
	?>
</div>
<?php
	require_once(TEMPLATES_PATH . "/footer.php");
?>

Yendo más lejos.

Aunque éste sistema de plantilla básica lo lleva a un gran comienzo, usted aún puede ir más lejos. Por ejemplo, usted puede crear una clase o funciones que incluyen todos los archivos de las plantillas y aceptan un archivo de contenido como un argumento para renderizarlo dentro de la composición. De esta manera usted no necesita continuar incluyendo los archivos de la plantilla en cada página de su sitio web, pero en lugar de abstracto que lógico lo que significa menos trabajo en el camino. Le mostraré un ejemplo rápido.

/resources/library/templateFunctions.php

<?php
	require_once(realpath(dirname(__FILE__) . "/../config.php"));

	function renderLayoutWithContentFile($contentFile, $variables = array())
	{
		$contentFileFullPath = TEMPLATES_PATH . "/" . $contentFile;
	
		// making sure passed in variables are in scope of the template
		// each key in the $variables array will become a variable
		if (count($variables) > 0) {
			foreach ($variables as $key => $value) {
				if (strlen($key) > 0) {
					${$key} = $value;
				}
			}
		}
	
		require_once(TEMPLATES_PATH . "/header.php");
	
		echo "<div id=\"container\">\n"
		   . "\t<div id=\"content\">\n";
	
		if (file_exists($contentFileFullPath)) {
			require_once($contentFileFullPath);
		} else {
			/*
				If the file isn't found the error can be handled in lots of ways.
				In this case we will just include an error template.
			*/
			require_once(TEMPLATES_PATH . "/error.php");
		}
	
		// close content div
		echo "\t</div>\n";
	
		require_once(TEMPLATES_PATH . "/rightPanel.php");
	
		// close container div
		echo "</div>\n";
	
		require_once(TEMPLATES_PATH . "/footer.php");
	}
?>

index.php

Esto es suponiendo que usted tiene un archivo llamado home.php en su directorio de plantillas que actúa como una plantilla de contenido.

<?php

	require_once(realpath(dirname(__FILE__) . "/../resources/config.php"));

	require_once(LIBRARY_PATH . "/templateFunctions.php");

	/*
		Now you can handle all your php logic outside of the template
		file which makes for very clean code!
	*/
	
	$setInIndexDotPhp = "Hey! I was set in the index.php file.";
	
	// Must pass in variables (as an array) to use in template
	$variables = array(
		'setInIndexDotPhp' => $setInIndexDotPhp
	);
	
	renderLayoutWithContentFile("home.php", $variables);

?>

home.php

<!-- Homepage content -->
<h2>Home Page</h2>

<?php

	/*
		Any variables passed in through the variables parameter in our renderLayoutWithContentPage() function
		are available in here.
	*/

	echo $setInIndexDotPhp;

?>

Los Beneficios de éste Método incluyen:

Mayor separación de lógica y vista (php y html). Separando problemas como esto hace un código más limpio, y el trabajo de los diseñadores o desarrolladores se vuelve más fácil debido a que ellos trabajan en su mayoría con sus respectivos códigos.
Encapsulando la plantilla logic en una función le permite hacer cambios para calcular cómo la plantilla renderiza sin actualizarlo en cada página de su sitio.

Symlinks

Un sistema basado en Unix (os x, linux) hay una pequeña funcionalidad estupenda llamada symlinks (Symbolic Links). Symlinks son referencias a directorios actuales o archivos en los archivos de sistemas. Esto es magnífico para cuando usted tiene un recurso compartido, tales como; una biblioteca usada entre múltiples proyectos. Aquí hay algunas cosas concretas que usted puede hacer con symlinks:

Tiene dos versiones de su directorio de recursos. Cuando actualiza su servidor en vivo, usted puede actualizar sus últimos archivos en un directorio arbitrario. Simplemente señale el symlink a este nuevo directorio e instantáneamente actualizará su código base. Si algo sale mal, puede retroceder instantáneamente al directorio anterior (el que estaba trabajando).
Comparte recursos que son fácilmente manejados con symlinks. Digamos que usted tiene una biblioteca personalizada en la que ha estado trabajando, cualquier actualización para la biblioteca que usted haga en un proyecto estará disponible, inmediatamente en otra.

Usando Symlinks

Symlinks versus Hardlinks

Symlinks, o softlinks, actúan como referencias a rutas completas en los archivos de sistemas. Usted puede usar symlinks en múltiples ubicaciones y los hilos de los archivos de sistemas como si fueran el archivo actual o directorio de referencia de ellos. Los hardlinks, por otra parte, son punteros hacia un archivo en el disco (considérelos como atajos en windows), ellos lo llevarán a la ubicación actual del archivo.

Hay algunas cosas que usted deberá de considerar cuando esté usando symlinks. La configuración de su servidor debe estar ajustada para seguir symlinks. Para el servidor Apache esto está hecho en el archivo httpd.conf. Encuentre el bloque Directory y asegúrese de que Optiones FollowSymlinks está ahí. Si no está, entonces agréguela y luego, reinicie el servidor Apache.

1	<Directory />
2	Options FollowSymLinks
3	AllowOverride None
4	</Directory>

Creando Symlinks en OS X

Hay dos maneras de crear symlinks en OS X:

A través de la línea de comando (cd, cambiar directorio) para el directorio en el cual usted quiere que symlink sea creado, luego use el siguiente comando:
1

$: ln -s /path/to/actual/dir targetDir
Pero si nuestro biblioteca personalizada vive en ~/Sites/libraries/myCustomLibrary cambiaríamos cd hacia donde quisiéramos usar esa biblioteca cd ~/Sites/mySite/resources/library e introducir:
1

$: ln -s ~/Sites/libraries/myCustomLibrary myCustomLibrary
Observe que este método debería de funcionar en todos los sistemas operativos basados en Unix.
La otra alternativa es a través del finder. Al mantener pulsada la tecla ALT + cmd mientras hace clic y arrastre un archivo, un Symlink (o alias en os x) que señala a el archivo que está creado.

Creando Symlinks en Windows

Para lograr esto en windows, necesitará usar el comando mklink en el comando prompt:

1
2	C:\mklink /D C:\libraries\myCustomLibrary C:\Users\derek\Sites\mySite\resources\library\myCustomLibrary

Resumen

Estos consejos se entiende que son para principiantes o para esos que crean sitios web o aplicaciones sencillas. Son ideales para grandes aplicaciones o sitios, usted querrá considerar algo más avanzado como la arquitectura MVC y la programación orientada a objetos. Lo animo a examinar estos una vez que haya conseguido que sus pies se mojen y sientan que superado la mayoría de los pasos anteriores. He decidido no abordar las fuentes de control, ya que es un tema bastante largo por sí mismo, pero estos consejos deberían ser suficientes para ayudarle en la organización de los archivos para un control de la fuente más fácil si lo desea (sugerencia: almacene cosas como las imágenes de la composición en su directorio de recursos y los symlinks en el directorio /public_html/img). Definitivamente, estudie el uso de las fuentes de control, como subversion o git para todos sus proyectos.

Espero que encuentre estos consejos útiles cuando empiece con su próximo proyecto PHP. ¡Gracias!

Recursos

Síguenos en Twitter, o suscribase a NETTUTS RSS Feed para más artículos y tutoriales de desarrollo web diarios.

1	<?php
2	require_once(realpath(dirname(__FILE__) . "/../config.php"));
3
4	function renderLayoutWithContentFile($contentFile, $variables = array())
5	{
6	$contentFileFullPath = TEMPLATES_PATH . "/" . $contentFile;
7
8	// making sure passed in variables are in scope of the template
9	// each key in the $variables array will become a variable
10	if (count($variables) > 0) {
11	foreach ($variables as $key => $value) {
12	if (strlen($key) > 0) {
13	${$key} = $value;
14	}
15	}
16	}
17
18	require_once(TEMPLATES_PATH . "/header.php");
19
20	echo "<div id=\"container\">\n"
21	. "\t<div id=\"content\">\n";
22
23	if (file_exists($contentFileFullPath)) {
24	require_once($contentFileFullPath);
25	} else {
26	/*
27	If the file isn't found the error can be handled in lots of ways.
28	In this case we will just include an error template.
29	*/
30	require_once(TEMPLATES_PATH . "/error.php");
31	}
32
33	// close content div
34	echo "\t</div>\n";
35
36	require_once(TEMPLATES_PATH . "/rightPanel.php");
37
38	// close container div
39	echo "</div>\n";
40
41	require_once(TEMPLATES_PATH . "/footer.php");
42	}
43	?>