# Resumen DPL UT4
## Documentación de Aplicaciones Web
En principio debemos documentar tres aspectos fundamentales de la aplicación:
- **La interfaz**: Qué hace (no como lo hace) una función o un método de una clase, qué parámetros hay que pasar y qué devuelve.
- **La implementación**: Indicar cómo está implementada cada función, cómo se lleva a cabo cada paso, por qué se utiliza determinada variable, qué algoritmo se utiliza, qué hacen los métodos privados de una clase.
- **La toma de decisiones**: Por qué se ha implementado de determinada forma y no de otra la aplicación, por ejemplo, para analizar el rendimiento de la aplicación y optimización de recursos.
Normalmente la información sobre la implementación no necesita salir del código pero, por el contrario, la información de la interfaz conviene pasarla a un documento independiente del código fuente (manual de uso), por lo que no es necesario ver el código fuente.
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. **Javadoc es la herramienta estándar en Java**. Para **PHP una de las herramientas más utilizadas es phpDocumentor**.
Los entornos de programación modernos, por ejemplo, son capaces de obtener la información de los comentarios, de forma que la muestran en el "autocompletado" de código, que se convierte en una herramienta estupenda, y aun imprescindible en lenguajes como PHP.
Hay que tener en cuenta que todas estas herramientas que venimos viendo, NetBeans, Eclipse, phpDocumentor, esperan el mismo tipo de comentarios, basado en el estándar establecido por JavaDoc, de modo que haremos el trabajo una sola vez y podremos aprovecharnos del mismo en varios entornos y con varias herramientas.
### phpDocumentor
Permite generar automáticamente una buena documentación de nuestro código, de una forma parecida a cómo lo hace JavaDoc.
phpDocumentor permite generar la documentación de varias formas y en varios formatos.
- Desde **línea de comandos** (php CLI - Command Line Interpreter).
- Desde **interfaz web** (incluida en la distribución).
- **Desde código**. Como phpDocumentor está desarrollado en PHP, podemos incluir su funcionalidad dentro de scripts propios.
En todo caso, es necesario especificar los siguientes parámetros:
- **El directorio en el que se encuentra nuestro código**. PhpDocumentor se encargará luego de recorrer los subdirectorios de forma automática.
- **Opcionalmente los paquetes** (@pakage) que deseamos documentar, lista de **ficheros incluidos y/o excluidos** y otras opciones interesantes para personalizar la documentación.
- **El directorio en el que se generará** la documentación.
- Si la documentación va a ser pública (sólo interfaz) o interna (en este caso aparecerán los bloques private y los comentarios @internal).
- El **formato de salida** de la documentación:
- **HTM**L a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida).
- **PDF**.
- **XML** (DocBook). Muy interesante puesto que a partir de este dialecto podemos transformar (XSLT) a cualquier otro utilizando nuestras propias reglas y hojas de estilo.
Una alternativa a **phpDocumentor es Doxygen** que puede también documentar código PHP, la principal diferencia es que Doxygen es un programa, mientras phpDocumentor es una colección de código en PHP.
#### DockBlock
En phpDocumentor la documentación se distribuye en bloques DocBlock. Estos bloques siempre se colocan justo antes del elemento al que documentan y su formato es:
```php=
<php
/**
* Descripción breve (una línea)
*
* Descripción extensa. Todas las líneas que
* sean necesarias
* Todas las líneas comienzan con *
<- Esta línea es ignorada
*
* Este DocBlock documenta la función suma()
*/
function suma()
{
...
}
```
Los elementos que pueden ser documentados son:
```php=
<?php
define
function
class
class vars
include/require/include_once/require_once
global variables
```
Además se puede incluir documentación global a nivel de fichero y clase mediante la marca **@package**
#### Marcas Estándar
| Marca | Significado |
| -------- | -------- |
| **@access** |Si @access es 'private' no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados).|
|**@author**|Autor del código|
|**@copyright**|Información sobre derechos|
|**@deprecated**|Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible.|
|**@example**|Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted).|
|**@ignore**|Evita que phpDocumentor documente un determinado elemento.|
|**@internal**|inline {@internal}} Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores.|
|**@link**|inline {@link} Para incluir un enlace (http://...) a un determinado recurso.|
|**@see**|Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento).|
|**@since**|Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución.|
|**@version**|Versión actual del elemento|
Ejemplo:
```php=
<?php
/**
* Emilious Sender (class worker) :)
*
* Envio de emails (MIME - multipart)
*
* Codificacion de mensajes segun RFC-822
* Utiliza la especificacion mime
* Permite enviar ficheros adjuntos utilizando
* Permite el envio a multiples destinatarios
*
* @author Enrique Fernandez-Perera [Epsilon Eridani]
* @author http://www.epsilon-eridani.com
*
* @package Emilious_Sender
*/
class Emilious_Sender
{
//// aqui la implementacion de la clase
}
```
#### Marcas Funciones
| Marca | Significado |
| -------- | -------- |
| @global | Permite especificar el uso de variables globales dentro de la función|
| @param | Parámetros que recibe la función. Formato: @param tipo $nombre_var comentario|
|@return |Valor devuelto por la función. Formato: @return tipo comentario|
**NOTA**: Tipos de datos en PHP (para indicar en @param, @return, etc...):
- array
- string
- boolean
- integer
- float
- object
- mixed
#### Ejemplos
- Ejemplo General:
```php=
<?php
/**
* Verifica si una direccion de correo es correcta o no.
*
* @return boolean true si la direccion es correcta
* @param string $email direccion de correo
*/
function check_dir_email ($email)
{
....
}
```
- Ejemplo de documentación de un método privado (la documentación no aparecerá a menos que se especifique de forma explícita):
```php=
<?php
/**
* localiza las imagenes dentro del contenido
*
* @access private
* @param string $dir_imagenes path al directorio de imagenes
*/
function encuentra_html_imagenes($dir_imagenes)
{
....
}
```
- Ejemplo de un comentario interno, @internal, que no aparecerá en la documentación de interfaz (documentación pública).
```php=
/**
* cuerpo del mensaje
*
* Para mandar texto HTML, $body tiene que ser un array
* de la forma (es preferible utilizar body_html()):
* $body['html'] = $texto_html;
* $body['texto'] = $texto_plano; (opcional)
* $body['dir_imagenes'] = $dir_imagenes; (opcional)
*
* @internal Si $this->body_con_html==true el valor de $ctype no se tiene en cuenta.
*
* @param mixed $body contenido del mensaje
* @param string $ctype (opcional) mime-type del contenido (text/plain si es texto)
* @param string $charset (opcional)
*/
function body($body, $ctype="", $charset="")
{
```
#### Variables de clase (atributos)
| Marca | Significado |
| -------- | -------- |
| @var|Documenta los atributos de la clase. Formato: @var tipo comentario|
Ejemplo:
```php=
/**
* array de destinatarios del mensaje
* @var array destinatarios
* @access private
*/
var $to;
```
---
## Control de Versiones
Se llama control de versiones a la gestión de los diversos cambios que se realizan sobre los elementos de algún producto o una configuración del mismo.
Una versión, revisión o edición de un producto, es el estado en el que se encuentra dicho producto en un momento dado de su desarrollo o modificación.
Aunque un sistema de control de versiones puede realizarse de forma manual, es muy aconsejable disponer de herramientas que faciliten esta gestión dando lugar a los llamados sistemas de control de versiones o SVC (System Version Control).
### Definiciones
- **Repositorio ("repository")**: Es el lugar en el que se almacenan los datos actualizados e históricos de cambios.
- **Revisión ("revision")**: Es una versión determinada de la información que se gestiona.
- **Etiqueta ("tag")**: Permiten identificar de forma fácil revisiones importantes en el proyecto. Por ejemplo, se suelen usar tags para identificar el contenido de las versiones publicadas del proyecto.
- **Rama ("branch")**: Conjunto de archivos que puede ser ramificado o bifurcado en un punto en el tiempo de manera que, a partir de ese momento, dos copias de esos archivos se pueden desarrollar de forma independiente el uno del otro.
- **Cambio ("change")**: Representa una modificación específica de un documento bajo el control de versiones.
- **Desplegar ("checkout")**: Crear una copia de trabajo local desde el repositorio.
- **Confirmar ("commit")**: Es escribir o mezclar los cambios realizados en la copia de trabajo del repositorio.
- **Conflicto ("conflict")**: Se produce cuando diferentes partes realizan cambios en el mismo documento y el sistema es incapaz de conciliar los cambios. Un usuario debe resolver el conflicto mediante la integración de los cambios, o mediante la selección de un cambio en favor del otro.
- **Cabeza ("head")**: Se refiere a la última confirmación, ya sea en el tronco ('trunk') o en una rama ('branch').
- **Tronco ("trunk")** La única línea de desarrollo que no es una rama (a veces también llamada línea base, línea principal o máster).
- **Fusionar, integrar, mezclar ("merge")**: Es una operación en la que se aplican dos tipos de cambios en un archivo o conjunto de archivos.
### Clasificación
- **Locales**: Los cambios son guardados localmente y no se comparten con nadie. Esta arquitectura es la antecesora de las dos siguientes.
- **Centralizados**: Existe un repositorio centralizado de todo el código, del cual es responsable un único usuario. Se facilitan las tareas administrativas a cambio de reducir flexibilidad, pues todas las decisiones fuertes necesitan la aprobación del responsable.
- **Distribuidos**: Cada usuario tiene su propio repositorio. Los distintos repositorios pueden intercambiar y mezclar revisiones entre ellos.
Ventajas de sistemas distribuidos
- No es necesario estar conectado para guardar cambios.
- Posibilidad de continuar trabajando si el repositorio remoto no está accesible.
- El repositorio central está más libre de ramas de pruebas. Se necesitan menos recursos para el repositorio remoto.
- Más flexibles al permitir gestionar cada repositorio personal como se quiera.
---
### Git
Git es un sistema de control de versiones. La mayoría de los demás sistemas almacenan la información como una lista de cambios en los archivos, mientras que Git modela sus datos más como un conjunto de instantáneas de un mini sistema de archivos.
#### Flujos de trabajo distribuidos
Git tiene tres estados principales en los que se pueden encontrar tus archivos:
- **Confirmado**: los datos están almacenados de manera segura en la base de datos local.
- **Modificado**: se ha modificado el archivo pero todavía no lo se ha confirmado a la base de datos.
- **Preparado**: se ha marcado un archivo modificado en su versión actual para que vaya en la próxima confirmación.
#### Flujos de trabajo centralizado
Existe un único repositorio o punto central que guarda el código y todo el mundo sincroniza su trabajo con él. Si dos desarrolladores clonan desde el punto central, y ambos hacen cambios, tan solo el primero de ellos en enviar sus cambios de vuelta lo podrá hacer limpiamente. El segundo desarrollador deberá fusionar previamente su trabajo con el del primero, antes de enviarlo, para evitar el sobreescribir los cambios del primero
#### Flujo de trabajo del Gestor-de-Integraciones
Al permitir múltiples repositorios remotos, en Git es posible tener un flujo de trabajo donde cada desarrollador tenga acceso de escritura a su propio repositorio público y acceso de lectura a los repositorios de todos los demás.
#### Flujo de trabajo con Dictador y Tenientes
Es una variante del flujo de trabajo con multiples repositorios. Se utiliza generalmente en proyectos muy grandes, con cientos de colaboradores. Unos gestores de integración se encargan de partes concretas del repositorio; y se denominan tenientes. Todos los tenientes rinden cuentas a un gestor de integración; conocido como el dictador benevolente. El repositorio del dictador benevolente es el repositorio de referencia, del que recuperan (pull) todos los colaboradores.
---
Para saber si tenemos instalado git, y conocer la versión, haremos uso de:
```bash=
git --version
```
#### Configuramos el usuario
Con --local: debemos crear primero nuestro repositorio.
Inicializamos el respositorio (nos creará una carpeta oculta):
```bash=
git init
```
Con --global:
```bash=
git config --local user.name "sara"
```
En el fichero config dentro de la carpeta oculta podremos ver que nos indica el usuario que hemos establecido.
```bash=
git config --local user.email "saracabrera13@hotmail.es"
```
Como podemos ver, dentro del VSCode en la esquina inferior izquierda, podemos observar que estamos trabajando dentro de la rama "master".
También podemos ver que el propio VSCode nos permite realizar configuraciones sin hacer uso de lineas de comando:
Pero en este caso vamos a continuar haciendo todo desde línea de comando:
Crearemos un fichero, en este caso un index.php con un "Hola mundo";
Pasaremos el archivo a stage:
```bash=
git add index.php
```
Comprobamos el estado de nuestro repositorio:
```bash=
git status
```
En caso de que queramos quitar nuestro fichero del stage haremos uso de:
```bash=
git rm --catched index.php
```
Ahora haremos uso de un commit (los nombres deben ser significativos):
```bash=
git commit -m "nombre"
```
El -m lo usamos para indicar que queremos ponerme un nombre/mensaje.
Si ahora hacemos un status veremos que nos indica que no hay nada que haya sido modificado actualmente.
Podemos ver las diferencias entre un cambio y otro pulsando en la línea al lado de nuestro código modificado:
El verde hace referencia a los nuevos cambios y, el rojo, a los cambios anteriores.
A continuación, podremos incluir los cambios con un "git add" o descartarlos con un "git restore".
Podemos indicar que queremos hacer un git a todos los ficheros dentro de nuestro repositorio haciendo uso de "git add ." (no maneja los cambios de ficheros eliminados).
Hacemos un add y un commit del fichero que acabamos de modificar.
- git add -u: añade todos los ficheros que ya pertenecían al repositorio (incluido los eliminados)
- git add -a: añade todos los ficheros que pertenecían y que no pertenecían al repositorio (incluido los eliminados)
- git add -n -a: hace una simulación de lo que nos haría el git add -a.
Modificamos una vez más el fichero index.php y le hacemos un commit.
Con el "git log" podremos ver los diferentes cambios que hemos realizado en nuestro repositorio (con "git log --oneline" podemos visualizarlo de manera más simple):
---
#### Alias de instrucciones
Podemos crear alias de un comando poniendo en el fichero config, dentro de nuestra carpeta oculta, algo como:
```bash=
[alias]
abreviatura: comando a sustituir
```
---
Para volver a versiones anteriores de nuestro repositorio podremos hacer uso de:
```bash=
git checkout "num_version"
```
Y veremos que la rama ha cambiado a la versión a la que nos hemos movido.
Para volver a la versión actual podremos hacerlo con "git checkout master".
Podemos ponerle tag a nuestras versiones usando:
```bash=
git tag "nombre"
```
Si tan solo ponemos "git tag" veremos todos los tags que hemos establecido.
## Despliegue en Heroku
Para desplegar en Heroku es necesario:
- Tener una cuenta de Heroku
- Tener créditos en Heroku
- Tener descargado Heroku CLI
- Tener Git
1. Lo primero que debemos hacer es congifurar el fichero **ProcFile**
2. **Logear** tu cuenta de Heroku con **heroku CLI**
3. **Creación del Proyecto** en Heroku
4. Hacer un **push a el repositorio** de nuestro proyecto en **Heroku**
5. **Generación de la Base de datos**, obteniendo una instancia de Base de Datos SQL y añadiendo las variables de conexión como variables de entorno. Para añadir las variables de entorno vamos a: Settings y en mostrar “config vars” verás el mismo link. Esto podemos hacerlo también con Heroku CLI
6. Generación de las Tablas con un SGBD como TablePlus
###### tags: `DAW` `DPL` `UT4`
Sign in with Wallet
Connect another wallet