From 65a108891f265c98584bac00cf383aceefae6ba5 Mon Sep 17 00:00:00 2001 From: Robert Sallent Date: Fri, 5 Apr 2024 19:54:18 +0200 Subject: [PATCH] v0.9.12 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Actualizaciones en la librería JSON. - Actualizaciones en la librería XML. --- app/libraries/JSON.php | 65 +++++++++++++++------------ app/libraries/Upload.php | 31 ++++++++----- app/libraries/XML.php | 94 ++++++++++++++++++++++++++-------------- test/library_json.php | 22 ++++++++++ test/library_xml.php | 20 +++++++++ 5 files changed, 163 insertions(+), 69 deletions(-) create mode 100644 test/library_json.php create mode 100644 test/library_xml.php diff --git a/app/libraries/JSON.php b/app/libraries/JSON.php index 86d60c1..92cb3e9 100644 --- a/app/libraries/JSON.php +++ b/app/libraries/JSON.php @@ -1,46 +1,57 @@ + */ 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 index d1d090f..bb19770 100644 --- 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 * @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 index 7df77f7..2bb1a4a 100644 --- a/app/libraries/XML.php +++ b/app/libraries/XML.php @@ -1,18 +1,30 @@ + */ 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(); @@ -20,37 +32,50 @@ public static function validateWithSchema( 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 new file mode 100644 index 0000000..1691b38 --- /dev/null +++ b/test/library_json.php @@ -0,0 +1,22 @@ +Test de la librería JSON"; + + echo "

Probando JSON::encode().

"; + + echo "

Intentando convertir a JSON dos usuarios decuperados desde la BDD.

"; + $usuarios = User::orderBy('id', 'ASC', 2); + $json = JSON::encode($usuarios, true, true); + echo "
$json
"; + + + echo "

Probando JSON::decode().

"; + + echo "

Mapeando a stdClass el JSON con los dos usuarios.

"; + dump(JSON::decode($json)); + + echo "

Mapeando a User el JSON con los dos usuarios.

"; + dump(JSON::decode($json, 'User')); + + + echo "

Probando el comportamiento ante un error, en caso de no lanzar excepciones.

"; + dump(JSON::decode('{test:error}', 'User', false)); \ No newline at end of file diff --git a/test/library_xml.php b/test/library_xml.php new file mode 100644 index 0000000..b62d227 --- /dev/null +++ b/test/library_xml.php @@ -0,0 +1,20 @@ +Test de la librería XML"; + + echo "

Probando XML::encode().

"; + + echo "

Intentando convertir a XML dos usuarios decuperados desde la BDD.

"; + $usuarios = User::orderBy('id', 'ASC', 2); + + $xml = XML::encode($usuarios, 'usuarios', 'user'); + echo "
".htmlspecialchars($xml)."
"; + + + echo "

Probando XML::decode().

"; + + echo "

Mapeando a stdClass el XML con los dos usuarios.

"; + dump(XML::decode($xml, 'stdClass', false)); + + echo "

Mapeando a User el XML con los dos usuarios.

"; + dump(XML::decode($xml, 'User', false)); +