MediaWiki - Cambios recientes [es]

PHP Documentación en PHP.

Angelfg — Wed, 14 Oct 2026 18:32:57 GMT

Página creada con «= Documentación do código en PHP = A documentación do código é unha práctica fundamental no desenvolvemento de software. En PHP, o estándar de documentación recoñ…»

Página nueva

= Documentación do código en PHP =

A documentación do código é unha práctica fundamental no desenvolvemento de software. En PHP, o estándar de documentación recoñecido pola comunidade é '''PHPDoc'''. Permite aos contornos de desenvolvemento (IDEs como VS Code ou PhpStorm) entender o tipo de datos co que se traballa, ofrecer autocompletado e detectar erros antes de executar o código.

 
== Tipos de comentarios en PHP ==

En PHP existen dous tipos de comentarios segundo o seu propósito:

 
=== 1. Comentarios de liña e bloque (para o programador) ===
Utilízanse para explicar o "porqué" dunha lóxica concreta dentro do fluxo do programa.

<syntaxhighlight lang="php">
// Comentario de liña única

# Outra forma de comentario de liña única (estilo Shell)

/*
Comentario de varias liñas.
Úsase para explicaciones máis extensas.
*/
</syntaxhighlight>

 
=== 2. Comentarios de documentación PHPDoc ===
Comezan sempre con <tt>/**</tt> (dous asteriscos) e colocanse xusto antes de arquivos, clases, métodos, funcións ou propiedades.

<syntaxhighlight lang="php">
/**
* Esto é un bloque PHPDoc.
* Describe o propósito xeral do elemento que ten debaixo.
*/
</syntaxhighlight>

 
== Estructura dun bloque PHPDoc ==

Un bloque PHPDoc consta de tres partes principais:
# '''Resumo (Summary):''' Unha liña curta que describe a función.
# '''Descrición detallada:''' (Opcional) Texto explicativo máis amplo.
# '''Etiquetas (Tags):''' Comezan por <tt>@</tt> e definen parámetros, tipos de retorno, excepcións, etc.

=== Etiquetas PHPDoc máis utilizadas ===

{| class="wikitable"
! Etiqueta !! Propósito !! Exemplo
|-
| <tt>@param</tt> || Define un parámetro de entrada nunha función. || <tt>@param string $nome Nome do usuario</tt>
|-
| <tt>@return</tt> || Define o tipo de dato e descrición do valor devoltos. || <tt>@return bool True se se gardou, false en caso contrario.</tt>
|-
| <tt>@throws</tt> || Excepcións que pode lanzar a función/método. || <tt>@throws PDOException Se falla a conexión coa BD.</tt>
|-
| <tt>@var</tt> || Especifica o tipo de dato duna variable ou propiedade. || <tt>@var PDO $conex Obxecto de conexión</tt>
|-
| <tt>@package</tt> || Organiza o código en paquetes ou módulos. || <tt>@package TiendaPerfumes</tt>
|-
| <tt>@author</tt> || Nome e correo do autor do código. || <tt>@author Angel <angel@example.com></tt>
|}

== Exemplo completo: Documentación dun script e funcións ==

<syntaxhighlight lang="php">
<?php
/**
* Script para o procesamento e alta de novos perfumes.
*
* Valida a entrada de datos mediante POST e realiza a inserción
* na base de datos previa comprobación de existencia.
*
* @package TiendaPerfumes
* @author Nome do Alumno <alumno@cifprodolfoucha.es>
* @version 1.0.0
*/

require_once '/var/www/confBD/ud3Angel.php';

/**
* Valida o prezo dun producto e comproba que estea dentro do rango permitido.
*
* @param mixed $prezoBruto Valor do prezo recibido da entrada (POST/GET).
* @param float $min Rango mínimo permitido (por defecto 5.0).
* @param float $max Rango máximo permitido (por defecto 500.0).
*
* @return float|false Devolve o prezo validado como float ou false se non é válido.
*/
function validarPrezo(mixed $prezoBruto, float $min = 5.0, float $max = 500.0): float|bool {
return filter_var($prezoBruto, FILTER_VALIDATE_FLOAT, [
'options' => ['min_range' => $min, 'max_range' => $max]
]);
}

/**
* Conecta coa base de datos PDO da aplicación.
*
* @return PDO Obxecto PDO activo.
* @throws PDOException Se ocorre un erro na autenticación ou conexión.
*/
function conectarBD(): PDO {
// Código de conexión...
}
</syntaxhighlight>

== Bonas prácticas ao comentar código ==

* '''Comenta o "Por que", non o "Que":''' Evita comentar o evidente. O código debe explicarse por si mesmo; os comentarios deben explicar decisións de deseño ou casos especiais.
* '''Mantén os comentarios actualizados:''' Un comentario desactualizado é peor que non ter ningún comentario.
* '''Usa tipos de datos claros:''' Especifica sempre o tipo de dato nas etiquetas (<tt>int</tt>, <tt>string</tt>, <tt>array</tt>, <tt>bool</tt>, <tt>PDO</tt>, etc.).
* '''Non inclúas datos sensibles:''' Nunca deixes contrasinais, claves API ou rutas privadas do servidor nos comentarios.

 -- [[Usuario:angelfg|Ángel D. Fernández González]] -- (2026).

Programación con PHP

Angelfg — Wed, 14 Oct 2026 18:30:02 GMT

UNIDADE 1: Inserción de código en páxinas web

PHP Operacións BD Mysql

Angelfg — Wed, 14 Oct 2026 18:03:39 GMT

Visualización de erros

Flutter Widget Componentes

Angelfg — Wed, 14 Oct 2026 07:32:51 GMT

Escalando las imágenes

PHP Paso de datos na URL

Angelfg — Thu, 08 Oct 2026 18:39:26 GMT

PHP UD3 OP CONSULTA

Angelfg — Thu, 08 Oct 2026 18:12:19 GMT

Comprobar se unha consulta SELECT devolveu datos

PHP UD3 OP ALTA

Angelfg — Thu, 08 Oct 2026 18:09:48 GMT

Número de filas afectadas

PHP UD3 OP CONSULTA

Angelfg — Thu, 08 Oct 2026 17:53:57 GMT

PHP UD3 TRANSACCIONS

Angelfg — Thu, 08 Oct 2026 11:39:03 GMT

Subida de imaxes

PHP Arrays

Angelfg — Thu, 08 Oct 2026 11:01:29 GMT

Funcións predefinidas relacionadas cos Arrays

PHP UD3 TRANSACCIONS

Angelfg — Thu, 08 Oct 2026 10:42:35 GMT

Mostrar los cambios

PHP UD3 EXERCICIOS PROPOSTOS

Angelfg — Thu, 08 Oct 2026 10:33:45 GMT

Comprobación final dos exercicios

Mostrar los cambios

Flutter Widget Componentes

Angelfg — Wed, 07 Oct 2026 17:10:06 GMT

Card Widget

Archivo:Flutter dart widget 32.png

Angelfg — Wed, 07 Oct 2026 17:08:48 GMT

Angelfg subió Archivo:Flutter dart widget 32.png

Página nueva

Flutter Widget Componentes

Angelfg — Wed, 07 Oct 2026 17:06:13 GMT

CircleAvatar

Archivo:Flutter dart widget 33.png

Angelfg — Wed, 07 Oct 2026 17:04:54 GMT

Angelfg subió Archivo:Flutter dart widget 33.png

Página nueva

Flutter Widget Componentes

Angelfg — Wed, 07 Oct 2026 17:00:55 GMT

CircleAvatar

Mostrar los cambios

@@ Línea 44: / Línea 44: @@
 *[[PHP Funcións para xerar código| Funcións para xerar código]]
 *[[PHP Constantes e variables. Ámbito. | Constantes e variables. Ámbito]]
+*[[PHP Documentación en PHP. | Documentación]]
 =='''UNIDADE 2: Programación baseada en linguaxes de marcas con código embebido'''==

@@ Línea 265: / Línea 265: @@
 [[Imagen:Mysql_visualuzar_erros_1.png|400px|center]]
 * <u>Outra ferramenta é engadir ao VS Code a extensión que nos permita facer 'debuger' da aplicación</u>. [https://wiki.cifprodolfoucha.es/index.php?title=PHP_Habilitar_depuraci%C3%B3n_en_VS_Code Tedes nesta misma wiki o procedemento para facelo na UD0 de instalación].
 <br />

@@ Línea 788: / Línea 788: @@
 </syntaxhighlight>
 * También podemos utilizar '''FittedBox''' para ajustar cualquier widget a las restricciones de su contenedor.
 <br />

@@ Línea 153: / Línea 153: @@
 ];
-$query = http_build_query(
+$query = http_build_query($parametros);
 $url = 'UD3_paso_var_Ex1_datos_pelicula.php?' . $query;
 </syntaxhighlight>
 * Se a URL vai ser inserida posteriormente dentro de HTML, tamén debemos escapar o seu valor para o contexto HTML:
@@ Línea 174: / Línea 168: @@
 ) ?>">PELÍCULA</a>
 </syntaxhighlight>
 <br />
@@ Línea 187: / Línea 204: @@
 ];
-$query = http_build_query(
+$query = http_build_query($parametros);
 $url = 'UD3_paso_var_Ex1_datos_pelicula.php?' . $query;
@@ Línea 400: / Línea 412: @@
 $query = http_build_query(
-     $parametros,
+     $parametros
 );
@@ Línea 413: / Línea 422: @@
 * Despois dunha redirección é recomendable empregar '''exit;''' para evitar que continúe a execución do script.
 <br />
 == Exercicio proposto ==
@@ Línea 574: / Línea 586: @@
 if ($erros !== []) {
      $query = http_build_query(
-         ['erros' => $erros],
+         ['erros' => $erros]
      );
@@ Línea 589: / Línea 598: @@
          'nome' => $nome,
          'dataNacemento' => $dataTexto
-     ],
 );

@@ Línea 176: / Línea 176: @@
-* Se realmente necesitamos coñecer o número de rexistros, realizaremos unha consulta específica empregando COUNT(*):
+* [https://www.php.net/manual/es/pdostatement.fetchcolumn.php fetchColum] permite recuperar da primeira fila a columna indicada. Se non poñemos ningunha columna recuperar a primeira.
 ::<syntaxhighlight lang="php">
 $stmt = $conex->query(
@@ Línea 255: / Línea 257: @@
 <br />
 === Recuperación de filas ===
 '''Paso 4: Agora necesitaremos percorrer dende o primeiro rexistro ata o último amosando o resultado.'''

@@ Línea 252: / Línea 252: @@
 Nun <code>INSERT</code> dunha única fila o normal é obter o valor <code>1</code> se a operación se realizou.
-'''Nota:''' non debemos utilizar <code>rowCount()</code> para determinar de forma portable o número de filas devoltas por un <code>SELECT</code>. Para un <code>SELECT</code> recuperaremos os datos con <code>fetch()</code> ou <code>fetchAll()</code>.
+'''Nota:''' non debemos utilizar <code>rowCount()</code> para determinar de forma portable o número de filas devoltas por un <code>SELECT</code>. Para un <code>SELECT</code> recuperaremos os datos con <code>fetch()</code>, <code>fetchColumn</code> ou <code>fetchAll()</code>.
 <br />

@@ Línea 2160: / Línea 2160: @@
                          'UTF-8'
                      ) ?>">
-         <input
+         <button
              type="submit"
-             value="BUSCAR">
+             value="BUSCAR">Buscar</button>
          <input
              type="reset"

@@ Línea 985: / Línea 985: @@
          ]);
          $autoresLibro = array_map(
              'intval',
@@ Línea 992: / Línea 996: @@
+             )
          );
+     }
@@ Línea 1687: / Línea 1692: @@
 Antes de iniciar a transacción validaremos que os arrays existen e teñen o mesmo número de elementos.
 ::<syntaxhighlight lang="php" enclose="div">
 <?php
@@ Línea 2002: / Línea 2009: @@
 <br />
 === Formulario para os exemplares ===
-A lista de estados debe consultarse unha única vez. O formulario completo de dúas fases inclúese a continuación:
+Na segunda fase do formulario de <code>alta_libro_exemplares.php</code> solicítanse os datos de cada exemplar.
-::<syntaxhighlight lang="php" enclose="div">
+Para xerar o formulario empréganse dous bucles:
-$estados = $stmt->fetchAll();
+:* Un bucle <code>for</code> que crea unha fila por cada exemplar indicado polo usuario.
-</syntaxhighlight>
+:* Un bucle <code>foreach</code> que percorre os estados dispoñibles para completar o elemento <code>&lt;select&gt;</code> de cada exemplar.
-Despois reutilizamos o array para todos os exemplares:
+A lista de estados recupérase da base de datos unha única vez mediante <code>CONSULTAR_ESTADOS</code> e almacénase no array <code>$estados</code>.
-::<syntaxhighlight lang="php" enclose="div">
+Deste xeito, reutilizamos os resultados da consulta para todos os exemplares, evitando realizar unha consulta SQL por cada fila do formulario.
-    <tr>
+Os campos empregan a notación <code>[]</code>:
-        <td>
+:* <code>lstEstado[]</code>
-            <select
+:* <code>txtImaxe[]</code>
-                name="lstEstado[]"
+:* <code>txtPrezo[]</code>
-                <?php foreach (
+Isto permite recibir os datos como arrays en PHP. Os elementos que ocupan a mesma posición nos tres arrays corresponden ao mesmo exemplar.
 <br />
@@ Línea 2327: / Línea 2274: @@
 Polo tanto haberá que deseñar tamén como desfacer ou limpar os ficheiros creados se a operación da base de datos falla.
 <br />

@@ Línea 679: / Línea 679: @@
 : En caso de que non nos importe o valor da clave podemos ordenar o array coa [http://php.net/manual/es/function.sort.php función sort]
 <br />
@@ Línea 697: / Línea 727: @@
 <br />
 == Arrays multidimensionais ==

@@ Línea 2427: / Línea 2427: @@
 * El aspecto final depende del tema de la aplicación, por lo que es preferible aprovechar el '''ThemeData''' en lugar de establecer manualmente colores y elevaciones en todos los widgets.
 '''Ejemplo'''
 :<syntaxhighlight lang="dart">

@@ Línea 2524: / Línea 2524: @@
    :* '''foregroundColor'''.
-'''Ejemplo actualizado'''
+'''Ejemplo'''
 :<syntaxhighlight lang="dart">