v0.9.12

- Actualizaciones en la librería JSON. - Actualizaciones en la librería XML.
robertsallent · Apr 5, 2024 · 65a1088 · 65a1088
1 parent f0adf2e
commit 65a1088
Show file tree

Hide file tree

Showing 5 changed files with 163 additions and 69 deletions.
diff --git a/app/libraries/JSON.php b/app/libraries/JSON.php
@@ -1,46 +1,57 @@
 <?php
 
-/*
- * Clase para la manipulación de JSON
- * Autor: Robert Sallent
- * Última revisión: 30/03/2023
+/**
+ *   Json
  *
- * */
-
+ *   Herramientas para trabajar con JSON desde PHP.
+ *
+ *   Última mofidicación: 05/04/2024
+ *
+ *   @author Robert Sallent <robertsallent@gmail.com>
+ */
 
 class JSON{
 
-    // codifica objetos en JSON (tanto listas como objetos sueltos)
+    /**
+     * Codifica objetos o arrays en JSON.
+     *
+     * @param mixed $objetos los datos a pasar a JSON.
+     * @param bool $exceptions permite indicar si se deben lanzar excepciones ante un fallo o no.
+     * @param bool $pretty permite indicar si queremos usar tabuladores y saltos de línea para una impresión amigable.
+     * 
+     * @return string el texto con los datos codificados en JSON.
+     */
     public static function encode(
-        $objetos,                   // datos a codificar en JSON
-        bool $exceptions = true,    // indica si se deben lanzar excepciones ante un error
-        bool $pretty = false        // impresión "bonita"
-
+        $datos, 
+        bool $exceptions = true, 
+        bool $pretty = false 
     ):string{
 
         return json_encode(
-                    $objetos, 
-                    JSON_UNESCAPED_UNICODE | 
-                    JSON_UNESCAPED_SLASHES | 
-                    JSON_NUMERIC_CHECK |
-                    ($exceptions ? JSON_THROW_ON_ERROR : 0) |
-                    ($pretty ? JSON_PRETTY_PRINT : 0)
-                );
+            $datos, 
+            JSON_UNESCAPED_UNICODE |  JSON_UNESCAPED_SLASHES |  JSON_NUMERIC_CHECK |
+                ($exceptions ? JSON_THROW_ON_ERROR : 0) |  ($pretty ? JSON_PRETTY_PRINT : 0)
+        );
     }
 
 
+    /**
+     * Decodifica JSON y lo convierte en una lista de objetos.
+     *
+     * @param string $json texto en JSON que queremos convertir a lista de objetos PHP.
+     * @param string $class clase a la que queremos convertir los objetos de primer nivel de profindidad.
+     * @param bool $exceptions permite indicar si se deben lanzar excepciones ante un fallo o no.
+     *
+     * @return array el listado de objetos recuperados.
+     */
 
-    // decodifica un JSON en una lista de objetos
     public static function decode(
-        string $json,                   // datos a decodificar
-        string $class = 'stdClass', // tipo de los objetos recuperados
-        bool $exceptions = true     // indica si se deben lanzar excepciones ante un error
-
-    ):array{
+        string $json,  
+        string $class = 'stdClass', 
+        bool $exceptions = true       
+    ):?array{
 
-        $lista = $exceptions ? 
-                    json_decode($json, false, 99, JSON_THROW_ON_ERROR):
-                    json_decode($json);
+        $lista = json_decode($json, false, 512, $exceptions? JSON_THROW_ON_ERROR : 0);
 
         // si hay error de sintaxis y no había que lanzar excepciones...
         if(json_last_error()) return NULL;

diff --git a/app/libraries/Upload.php b/app/libraries/Upload.php
@@ -12,7 +12,7 @@
   *  Aún así se mantiene esta clase para la realización de distintos ejemplos docentes 
   *  en los cursos de PHP y desarrollo de aplicaciones web.
   *  
-  *  Última mofidicación: 05/07/23
+  *  Última mofidicación: 05/04/24
   *  
   *  @author Robert Sallent <robertsallent@gmail.com>
   *  @since v0.1.0
@@ -56,16 +56,27 @@ public static function uniqueName(
     }
 
 
-
-    // procesa la subida de un fichero y hace todas las comprobaciones
+    /**
+     * Procesa la subida de un fichero y hace todas las comprobaciones necesarias.
+     * 
+     * @param string $key clave de $_FILES (nombre del input).
+     * @param string $folder carpeta de destino.
+     * @param bool $unique generar nombre único?.
+     * @param int $max tamaño max del fichero (0 ilimitado).
+     * @param string $mime tipo MIME (image/jpeg, image/*, etc).
+     * @param string $prefix prefijo para el nombre del fichero.
+     * @param bool $returnFullRoute retornar la ruta final completa o solo el nombre del fichero.
+     * 
+     * @return string nombre final del fichero o ruta completa en la que queda ubicado.
+     */
     public static function save(
-        string $key = 'file',  // clave de $_FILES (nombre del input)
-        string $folder = '',   // carpeta de destino
-        bool $unique = true,   // generar nombre único?
-        int $max = 0,          // tamaño max del fichero (0 ilimitado)
-        string $mime = '.',    // tipo MIME (image/jpeg, image/*, etc)
-        string $prefix = '',   // prefijo para el nombre del fichero
-        bool $returnFullRoute = false  // retorna la ruta final completa o solo el nombre del fichero
+        string $key = 'file', 
+        string $folder = '', 
+        bool $unique = true, 
+        int $max = 0,
+        string $mime = '.',
+        string $prefix = '',
+        bool $returnFullRoute = false 
     ):string{
 
         // comprobar que llega algo con la clave indicada

diff --git a/app/libraries/XML.php b/app/libraries/XML.php
@@ -1,56 +1,81 @@
 <?php
-/* 
- * Clase para la manipulación de XML
- * Autor: Robert Sallent
- * Última revisión: 28/02/2022
- * 
- * */
+
+/**
+ *   XML
+ *
+ *   Herramientas para trabajar fácilmente con XML desde PHP.
+ *
+ *   Última mofidicación: 05/04/2024
+ *
+ *   @author Robert Sallent <robertsallent@gmail.com>
+ */
 
 class XML{
 
-    // método que valida con XMLSchema
+    /**
+     * Valida un XML a partir de un XMLSchema
+     *
+     * @param string $xml XML a validar.
+     * @param string $schema esquema contra el que se quiere realizar la validación.
+     *
+     * @return bool true si valida o false si no lo hace.
+     * 
+     * @throws XMLException si no se puede cargar el XML.
+     */
     public static function validateWithSchema(
         string $xml, 
-        string $esquema
-
+        string $schema   
     ):bool{
 
         $dom = new DOMDocument();
 
         if(!@$dom->loadXML($xml)) // intenta cargar el XML
             throw new XMLException("XML mal formado.");
 
-        return $dom->schemaValidate($esquema);
+        return $dom->schemaValidate($schema);
     }
 
 
 
-    // convierte listas de cualquier tipo de objeto en XML.
+    /**
+     * Convierte listas de elementos a XML.
+     * 
+     * @param array $lista lista de elementos a convertir.
+     * @param string $root nombre para el elemento raíz.
+     * @param string $name nombre para cada uno de los elementos contenidos directamente dentro del elemento raíz.
+     * @param string $namespace espacio de nombres a usar.
+     * 
+     * @return string el XML con el resultado.
+     */
     public static function encode(
-        array  $lista = [],         // lista de elementos a codificar
-        string $root = 'root',      // nombre del elemento raíz
-        string $name = null,        // nombre para cada elemento
-        string $namespace = 'http://ejemplo.xml.robertsallent.cat'
-
+        array  $list     = [],
+        string $root      = 'root',
+        string $name      = null,
+        string $namespace = "https://xml.robertsallent.com"       
     ):string{
-            
+
         // crea el documento XML con las opciones adecuadas
         $xml = new DOMDocument("1.0", "utf-8");
         $xml->preserveWhiteSpace = false;
         $xml->formatOutput = true;
-        
+
         $raiz = $xml->createElement($root); // crea el elemento raíz
         $raiz->setAttribute('xmlns', $namespace); // pone el namespace
-        
-        foreach($lista as $objeto){ // para cada objeto de la lista
+
+        foreach($list as $objeto){ // para cada objeto de la lista
             // crea un nuevo elemento con el nombre indicado
             // si no estaba indicado, usará el nombre de la clase en minúscula
             $nombre = $name ?? strtolower(get_class($objeto));
             $elemento = $xml->createElement($nombre);
 
-            foreach($objeto as $campo=>$valor) // para cada propiedad del objeto...
-                $elemento->appendChild($xml->createElement($campo, $valor));
+            foreach($objeto as $campo => $valor){ // para cada propiedad del objeto...
+
+                // corrección para que funcionen los campos JSON con arrays
+                if(is_array($valor))
+                    $valor = arrayToString($valor, true, false);
 
+                $elemento->appendChild($xml->createElement($campo, $valor));
+            }
             // añade el nuevo elemento al elemento raíz
             $raiz->appendChild($elemento);
         }
@@ -64,18 +89,23 @@ public static function encode(
 
 
 
-    // Método que recupera objetos desde un XML
+    /**
+     * Recupera objetos desde un origen XML
+     * 
+     * @param string $origin origen de datos XML.
+     * @param string $class nombre de la clase a la que queremos mapear los objetos recuperados en primer nivel de profundidad.
+     * @param bool $file para indicar si los datos llegan de fichero (true) o url (false).
+     * 
+     * @return array lista de objetos PHP recuperados desde el XML.
+     */
     public static function decode(
-        string $origen,             // origen del XML
-        string $clase = 'stdClass', // clase a la que se mapeará
-        bool $fichero = true        // XML desde fichero?
-        
+        string $origin,
+        string $class = 'stdClass',
+        bool $file    = true 
     ):array{
 
-        // cargamos el XML depediendo de si es de fichero o string
-        $xml = $fichero ?
-            simplexml_load_file($origen):
-            simplexml_load_string($origen);
+        // carga el XML depediendo de si es de fichero o string
+        $xml = $file ? simplexml_load_file($origin) : simplexml_load_string($origin);
 
         // si no se pudo recuperar bien el XMl, se lanza una excepción
         if(!$xml)
@@ -85,7 +115,7 @@ public static function decode(
 
         // para cada objeto que encontremos en el XML...
         foreach($xml as $objetoXML){
-            $objeto = new $clase(); // crea un nuevo objeto
+            $objeto = new $class(); // crea un nuevo objeto
 
             // mapea los datos del XML al objeto
             foreach($objetoXML as $campo=>$valor)

diff --git a/test/library_json.php b/test/library_json.php
@@ -0,0 +1,22 @@
+<?php
+    echo "<h1>Test de la librería JSON</h1>";
+
+    echo "<h2>Probando JSON::encode().</h2>";
+
+    echo "<p>Intentando convertir a JSON dos usuarios decuperados desde la BDD.</p>";
+    $usuarios = User::orderBy('id', 'ASC', 2);
+    $json = JSON::encode($usuarios, true, true);
+    echo "<pre>$json</pre>";
+
+
+    echo "<h2>Probando JSON::decode().</h2>";
+
+    echo "<p>Mapeando a stdClass el JSON con los dos usuarios.</p>";
+    dump(JSON::decode($json));
+
+    echo "<p>Mapeando a User el JSON con los dos usuarios.</p>";
+    dump(JSON::decode($json, 'User'));
+
+
+    echo "<p>Probando el comportamiento ante un error, en caso de no lanzar excepciones.</p>";
+    dump(JSON::decode('{test:error}', 'User', false));
diff --git a/test/library_xml.php b/test/library_xml.php
@@ -0,0 +1,20 @@
+<?php
+    echo "<h1>Test de la librería XML</h1>";
+
+    echo "<h2>Probando XML::encode().</h2>";
+
+    echo "<p>Intentando convertir a XML dos usuarios decuperados desde la BDD.</p>";
+    $usuarios = User::orderBy('id', 'ASC', 2);
+
+    $xml = XML::encode($usuarios, 'usuarios', 'user');
+    echo "<pre>".htmlspecialchars($xml)."</pre>";
+
+
+    echo "<h2>Probando XML::decode().</h2>";
+
+    echo "<p>Mapeando a stdClass el XML con los dos usuarios.</p>";
+    dump(XML::decode($xml, 'stdClass', false));
+
+    echo "<p>Mapeando a User el XML con los dos usuarios.</p>";
+    dump(XML::decode($xml, 'User', false));
+