diff --git a/appendices/migration86/new-features.xml b/appendices/migration86/new-features.xml index a74cae158..494c2e96d 100644 --- a/appendices/migration86/new-features.xml +++ b/appendices/migration86/new-features.xml @@ -1,5 +1,5 @@ - + Nuevas características @@ -12,7 +12,12 @@ Las propiedades - readonly ahora pueden declarar valores por defecto. + readonly, incluidas las de las + clases readonly, + ahora pueden declarar valores por defecto. + El valor por defecto cuenta como la inicialización de la propiedad, por lo + que la propiedad no puede volver a asignarse, ni siquiera desde el + constructor. @@ -146,8 +151,9 @@ class Package implements HasVersion Aplicación parcial de funciones - Se ha añadido soporte para la aplicación parcial de funciones. Una llamada - en la que uno o más argumentos se sustituyen por el marcador + Se ha añadido soporte para la + aplicación parcial de funciones. + Una llamada en la que uno o más argumentos se sustituyen por el marcador ?, o los argumentos restantes por el marcador ..., crea una Closure que acepta los argumentos que faltan. @@ -475,7 +481,7 @@ bool(true) session_remove_cb num_tickets - + @@ -601,9 +607,11 @@ bool(true) Las enumeraciones StreamErrorStore, StreamErrorMode y StreamErrorCode Las funciones stream_last_errors y stream_clear_errors - Se controla mediante las opciones de contexto de flujo + Se controla mediante las + opciones de contexto de flujo error_mode, error_store y error_handler. + Consulte para una visión general. diff --git a/appendices/migration86/other-changes.xml b/appendices/migration86/other-changes.xml index 48f1820c2..ea09e6b79 100644 --- a/appendices/migration86/other-changes.xml +++ b/appendices/migration86/other-changes.xml @@ -1,5 +1,5 @@ - + Otros cambios @@ -86,6 +86,25 @@ Anteriormente, estos fallos se ignoraban silenciosamente. + + stream_select, + stream_copy_to_stream, + stream_socket_pair y + stream_is_local ahora tienen un argumento opcional + adicional context. + + + + + stream_context_set_default ahora lanza una + ValueError si + options contiene alguna de las + opciones de contexto de flujo + error_mode, error_store o + error_handler. + + + @@ -389,7 +408,7 @@ array_map que utilice como retrollamada un callable de primera clase o una - aplicación + aplicación parcial de función se compilará como el bucle foreach equivalente, evitando la creación de Closure intermedias y el diff --git a/language/constants.xml b/language/constants.xml index a5089a424..1cf0049ae 100644 --- a/language/constants.xml +++ b/language/constants.xml @@ -1,5 +1,5 @@ - + Constantes @@ -242,6 +242,14 @@ echo ANIMALS_DEF[1] . "\n"; // muestra "cat" + + 8.6.0 + + Se añadió el soporte de la + aplicación parcial de + funciones en las expresiones constantes. + + 8.5.0 diff --git a/language/context.xml b/language/context.xml index 19200bf91..566ffbc3d 100644 --- a/language/context.xml +++ b/language/context.xml @@ -1,5 +1,5 @@ - + @@ -15,6 +15,7 @@ +&language.context.stream; &language.context.socket; &language.context.http; &language.context.ftp; diff --git a/language/context/stream.xml b/language/context/stream.xml new file mode 100644 index 000000000..788ea738e --- /dev/null +++ b/language/context/stream.xml @@ -0,0 +1,274 @@ + + + + + + Opciones de contexto de stream + Lista de opciones de contexto para la gestión de errores de los streams + + + + &reftitle.description; + + Las opciones bajo la clave stream están disponibles para + todos los wrappers. Controlan cómo se notifican los errores de las + operaciones de stream que utilizan el contexto. + Consulte para obtener una visión general. + + + + + &reftitle.options; + + + error_mode StreamErrorMode + + + Cómo se notifican los errores: como diagnósticos del tipo + E_WARNING + (StreamErrorMode::Error), + lanzando una StreamException para los + errores terminales (StreamErrorMode::Exception), + o no notificándolos en absoluto (StreamErrorMode::Silent). + + + Por defecto es StreamErrorMode::Error. + + + + + error_store StreamErrorStore + + + Qué errores se almacenan para poder recuperarlos con + stream_last_errors. + + + Por defecto es StreamErrorStore::Auto, que + no almacena ningún error con StreamErrorMode::Error, + almacena los errores no terminales con StreamErrorMode::Exception + y almacena todos los errores con StreamErrorMode::Silent. + + + + + error_handler callable + + + Una retrollamada que se invoca una vez por cada operación que haya + notificado errores, con la siguiente firma: + + + voidhandler + arrayerrors + + + + errors + + + Una lista de objetos StreamError con todos + los errores de la operación, en el orden en que fueron notificados. + + + + + + El manejador se invoca independientemente de error_store, + una vez que los errores han sido notificados como diagnósticos. No se invoca + si se lanza una StreamException. + Su valor de retorno se ignora. + + + + + + + + &reftitle.errors; + + Los valores de estas opciones no se validan cuando se crea el contexto. + Si una operación notifica un error y + error_mode no es un + StreamErrorMode, error_store + no es un StreamErrorStore, o + error_handler no es un + callable válido, se lanza una TypeError. + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.6.0 + + Se añadieron error_mode, + error_store y + error_handler. + + + + + + + + + &reftitle.notes; + + + Estas opciones no se pueden establecer con + stream_context_set_default, que lanza una + ValueError si se pasan estas opciones. + + + + + Solo se ven afectados los errores de la capa de streams. Los demás errores de una + función, como una ValueError o una + TypeError por un argumento no válido, + se lanzan como de costumbre. + + + + + + &reftitle.examples; + + Lanzar excepciones ante errores de stream + + [ + 'error_mode' => StreamErrorMode::Exception, + ], +]); + +try { + $stream = fopen('/nonexistent/file.txt', 'r', false, $context); +} catch (StreamException $exception) { + echo $exception->getMessage(), PHP_EOL; + + foreach ($exception->getErrors() as $error) { + echo $error->wrapperName, ': ', $error->code->name, PHP_EOL; + } +} +]]> + + &example.outputs; + + + + + + Recuperar errores sin diagnósticos + + [ + 'error_mode' => StreamErrorMode::Silent, + ], +]); + +$stream = fopen('/nonexistent/file.txt', 'r', false, $context); +var_dump($stream); + +foreach (stream_last_errors() as $error) { + echo $error->code->name, ': ', $error->message, PHP_EOL; +} +]]> + + &example.outputs; + + + + + + Recibir los errores en un manejador de errores + + [ + 'error_mode' => StreamErrorMode::Silent, + 'error_store' => StreamErrorStore::None, + 'error_handler' => function (array $errors): void { + print_r($errors); + }, + ], +]); + +fopen('/nonexistent/file.txt', 'r', false, $context); +]]> + + &example.outputs; + + StreamError Object + ( + [code] => StreamErrorCode Enum + ( + [name] => OpenFailed + ) + + [message] => Failed to open stream: No such file or directory + [wrapperName] => plainfile + [severity] => 2 + [terminating] => 1 + ) + +) +]]> + + + + + + &reftitle.seealso; + + stream_context_create + stream_last_errors + StreamError + StreamException + + + + + diff --git a/language/functions.xml b/language/functions.xml index a011b7921..eea34f473 100644 --- a/language/functions.xml +++ b/language/functions.xml @@ -1,5 +1,5 @@ - + Functions @@ -1714,6 +1714,31 @@ $privateMethod(); // Foo1::privateMethod + + A partir de PHP 8.6.0, se pueden proporcionar algunos de los argumentos + al crear la Closure, utilizando el marcador de + posición ? para los demás. Consulte + aplicación parcial de funciones. + + Aplicación parcial de funciones simple + +method(1, ?); // acepta $second +$partial2 = $obj->method(?, 2); // acepta $first +$partial3 = Foo::staticmethod(1, ...); // acepta todos los argumentos restantes +]]> + + + + Object creation by this syntax (e.g new Foo(...)) is not supported, because new Foo() syntax is not considered a call. @@ -1760,6 +1785,305 @@ $obj?->prop->method(...); + + Aplicación parcial de funciones + + + La aplicación parcial de funciones está disponible a partir de PHP 8.6.0. + Una llamada a una función o método que proporciona algunos de los + argumentos y utiliza marcadores de posición para los demás no realiza la + llamada. En su lugar, crea una Closure cuyos + parámetros son aquellos que fueron reemplazados por un marcador de + posición. Extiende la + sintaxis de callable de primera clase, + que es el caso particular en el que no se proporciona ningún argumento: + se puede utilizar cualquier expresión que pueda ser llamada, y la función + o método a llamar se determina cuando se crea la + Closure. + + + + + + ? representa exactamente un argumento. El parámetro + correspondiente de la Closure siempre es + obligatorio, incluso si el parámetro de la función original es + opcional. + + + + + ... representa todos los parámetros que no se han + mencionado de otro modo. Estos conservan sus valores por defecto, y un + parámetro variádico sigue siendo variádico. Solo puede aparecer una + vez, y debe ser el último argumento. + + + + + + Aplicación parcial de funciones + + volume(2, $width, 4) +var_dump($closure(3)); + +$closure = volume(?, 3, ?); +// equivalente a: static fn(int $length, int $height): int => volume($length, 3, $height) +var_dump($closure(2, 4)); + +// "..." representa todos los argumentos restantes +$closure = volume(2, ...); +// equivalente a: static fn(int $width, int $height): int => volume(2, $width, $height) +var_dump($closure(3, 4)); + +// Con todos los argumentos proporcionados, "..." simplemente retrasa la llamada +$closure = volume(2, 3, 4, ...); +// equivalente a: static fn(): int => volume(2, 3, 4) +var_dump($closure()); +?> +]]> + + &example.outputs; + + + + + + + La aplicación parcial de funciones es una forma práctica de proporcionar + el callable de un solo parámetro que espera el + operador pipe. + + + + Aplicación parcial de funciones con <literal>|></literal> + + trim(...) + |> str_replace(' ', '', ?) + |> strtoupper(...) + |> str_pad(?, 12, '*', STR_PAD_BOTH); +?> +]]> + + &example.outputs; + + + + + + + Los parámetros de la Closure toman su nombre, su + declaración de tipo y su modo de paso por referencia de la función + original, así como su tipo de retorno. La aplicación parcial de funciones + puede utilizarse en expresiones constantes, siempre que los argumentos + sean a su vez expresiones constantes. + + + + Marcadores de posición con nombre + + + Se pueden utilizar argumentos + nombrados para proporcionar un argumento, y un marcador de + posición también puede llevar nombre, mediante name: ?. Como + en una llamada normal, deben ir después de los argumentos posicionales. + Los parámetros de la Closure siguen el orden en + que se escriben los marcadores de posición con nombre, lo que permite + reordenarlos. + + + + Marcadores de posición con nombre + + +]]> + + &example.outputs; + + + + + + + + Evaluación de los argumentos + + + Los argumentos proporcionados se evalúan una sola vez, cuando se crea la + Closure, y no cada vez que se la llama. Esto + difiere de una función flecha que + envuelve la misma llamada, cuyo cuerpo se evalúa en cada llamada. + + + + Los argumentos se evalúan cuando se crea la <classname>Closure</classname> + + greet($name, now()); +echo "Arrow function created\n"; +echo $arrow('Alice'); + +$partial = greet(?, now()); +echo "Partial application created\n"; +echo $partial('Bob'); +?> +]]> + + &example.outputs; + + + + + + + + Argumentos adicionales + + + Si no se utiliza el marcador de posición ..., los argumentos + pasados a la Closure más allá de sus parámetros + se ignoran. Si se utiliza, se reenvían a la función original. Esto es + relevante cuando la Closure se usa como + retrollamada de una función que pasa más argumentos de los esperados, + como la clave de un elemento de un array: con ... estos + llegan a los parámetros opcionales de la función original. + + + + Los argumentos adicionales solo se reenvían con <code>...</code> + + +]]> + + &example.outputs; + + + + + + + + Restricciones + + + + + La creación de objetos (por ejemplo new Foo(1, ?)) no + está soportada, porque la sintaxis new Foo() no se + considera una llamada. + + + + + Los marcadores de posición no se pueden combinar con el + operador nullsafe. + + + + + Los marcadores de posición no se pueden combinar con el + desempaquetado de argumentos. + + + + + No se pueden utilizar funciones que inspeccionan el ámbito de llamada, + como compact, extract, + func_get_args y + get_defined_vars. + Se lanza un Error. + + + + + + Usos no válidos que provocan un error en tiempo de compilación + +method(1, ?); // Cannot combine nullsafe operator with Closure creation + +foo(?, ...$array); // Cannot combine partial application and unpacking + +foo(..., ?); // Variadic placeholder must be last +foo(a: 1, ?); // Cannot use positional argument after named argument +]]> + + + + + Se lanza un ArgumentCountError cuando se + crea la Closure si el número de argumentos y + marcadores de posición no coincide con los parámetros de la función. + + + + + Sintaxis básica @@ -184,6 +184,11 @@ readonly class Foo ]]> + + A partir de PHP 8.6.0, las propiedades de una clase readonly + pueden declarar + valores por defecto. + Una clase readonly puede ser extendida si, @@ -776,6 +781,50 @@ NS\ClassName ]]> + + Utilizar ::class sobre un valor que no es un objeto + lanza una excepción TypeError. Esto incluye + un string que contenga el nombre de una clase, el cual puede + utilizarse directamente en su lugar. + + + Utilización de <literal>::class</literal> sobre un string + +getMessage(); +} +?> +]]> + + &example.outputs.83; + + + + &example.outputs.82; + + + + + + + Cuando se utiliza sobre un literal de tipo string, como en + 'ClassName'::class, ::class se + resuelve durante la compilación y se evalúa como el nombre de clase + contenido en el string, tomado como un nombre completamente cualificado: + no se resuelve con respecto al espacio de nombres actual, y se elimina + la barra invertida inicial. + + Métodos y propiedades nullsafe diff --git a/language/oop5/properties.xml b/language/oop5/properties.xml index d68a8e00e..7ed418a3a 100644 --- a/language/oop5/properties.xml +++ b/language/oop5/properties.xml @@ -1,5 +1,5 @@ - + Propiedades @@ -290,33 +290,53 @@ new Test('abc 42'); - - - Especificar un valor por defecto explícito a una propiedad de solo lectura - no está permitido, ya que una propiedad de solo lectura con un valor por defecto es esencialmente idéntica a una constante, y por lo tanto - no particularmente útil. - - + + A partir de PHP 8.6.0, una propiedad de solo lectura puede declarar un valor + por defecto. + El valor por defecto cuenta como la inicialización de la propiedad, por lo + que la propiedad no puede volver a asignarse, ni siquiera desde el + constructor. + Esto permite implementar una + propiedad de interfaz + de solo lectura con un valor fijo, sin tener que asignarla en un constructor. + Antes de PHP 8.6.0, declarar un valor por defecto en una propiedad de solo + lectura provocaba un error en tiempo de compilación. + + + +$test = new Test(); +var_dump($test->prop); // int(42) + +// La propiedad ya ha sido inicializada por su valor por defecto. +$test->prop = 43; +// Error: Cannot modify readonly property Test::$prop ]]> - - - + + + + + + Un valor por defecto en un + parámetro de constructor promocionado + es el valor por defecto del parámetro, no el de la propiedad. + - + Las propiedades de solo lectura no pueden ser unset una vez que han sido inicializadas. Sin embargo, es posible unset una propiedad de solo lectura antes de su inicialización, desde el ámbito donde la propiedad fue declarada. - + Una propiedad de solo lectura con un valor por defecto se inicializa al crear + el objeto, y por lo tanto nunca puede ser unset. + Las modificaciones no son necesariamente asignaciones simples, diff --git a/language/operators/functional.xml b/language/operators/functional.xml index a569ba38e..db941dd98 100644 --- a/language/operators/functional.xml +++ b/language/operators/functional.xml @@ -1,5 +1,5 @@ - + Operadores funcionales @@ -87,6 +87,37 @@ Array [7] => K [8] => S ) +]]> + + + + + A partir de PHP 8.6.0, la + aplicación parcial de funciones + puede utilizarse para pasar un valor mediante pipe a una función que recibe + varios parámetros, sin envolver la llamada en una función de flecha. El + marcador ? indica el argumento que recibe el valor del + lado izquierdo. + + Uso de la aplicación parcial de funciones con |> + + htmlentities(...) + |> str_split(...) + |> array_map(strtoupper(...), ?) + |> array_filter(?, fn($letter) => $letter != 'O') + |> implode('', ?) +; +echo $result, PHP_EOL; +?> +]]> + + &example.outputs; + + diff --git a/language/types/callable.xml b/language/types/callable.xml index d04b5376d..dc461d4d9 100644 --- a/language/types/callable.xml +++ b/language/types/callable.xml @@ -1,5 +1,5 @@ - + Callables @@ -68,13 +68,17 @@ function foo(callable $callback) { funciones anónimas, sintaxis de funciones de flecha, sintaxis callable de primera - clase, o el método Closure::fromCallable. + clase, + aplicación parcial de + funciones, o el método Closure::fromCallable. La sintaxis callable de primera - clase solo está disponible a partir de PHP 8.1.0. + clase solo está disponible a partir de PHP 8.1.0, y la + aplicación parcial de + funciones a partir de PHP 8.6.0. diff --git a/reference/stream/book.xml b/reference/stream/book.xml index 42aec4882..bb5bc93b9 100644 --- a/reference/stream/book.xml +++ b/reference/stream/book.xml @@ -1,6 +1,6 @@ - + @@ -75,6 +75,11 @@ &reference.stream.php-user-filter; &reference.stream.streamwrapper; &reference.stream.streambucket; + &reference.stream.streamerror; + &reference.stream.streamexception; + &reference.stream.streamerrorcode; + &reference.stream.streamerrormode; + &reference.stream.streamerrorstore; &reference.stream.reference; diff --git a/reference/stream/entities.ent b/reference/stream/entities.ent new file mode 100644 index 000000000..4128957c7 --- /dev/null +++ b/reference/stream/entities.ent @@ -0,0 +1,22 @@ + + + + + + + + + Un contexto resource creado con + stream_context_create, o &null;. + Sus opciones de gestión de errores + determinan cómo se notifican los errores de flujo de esta llamada. + + + + diff --git a/reference/stream/errors.xml b/reference/stream/errors.xml index eaa03ebb8..b54476cb9 100644 --- a/reference/stream/errors.xml +++ b/reference/stream/errors.xml @@ -1,6 +1,6 @@ - + Errores de Flujos @@ -8,12 +8,110 @@ Como con cualquier función relacionada con un archivo o con un socket, una operación sobre un flujo puede fallar por varias razones normales (esto es: Incapaz de conectarse al host remoto, archivo no encontrado, etc...). Una llamada relacionada con un flujo puede también fallar - porque el flujo no está registrado en el sistema en ejecución. Véase la matriz devuelta + porque el flujo no está registrado en el sistema en ejecución. Véase el array devuelto por stream_get_wrappers para una lista de los flujos soportados por su instalación de PHP. Como con la mayoría de la funciones internas de PHP, si ocurre un error se generará un mensaje E_WARNING describiendo la naturaleza del error. + +
+ Configuración del manejo de errores + + A partir de PHP 8.6.0, la forma en que se informan los errores de flujo puede + cambiarse para cada operación que utilice un + contexto de flujo, estableciendo las + opciones de contexto de flujo + error_mode, error_store + y error_handler. + Cada error se describe mediante un objeto StreamError, + cuya propiedad code + es un caso de StreamErrorCode. + + + Un error es o bien terminante, como un fichero que + no puede abrirse, o bien no terminante, en cuyo caso se + informa pero no lanza una excepción en el modo StreamErrorMode::Exception. + Una sola operación puede informar de varios errores. + + + La opción error_mode recibe un caso de + StreamErrorMode y selecciona cómo se + informan los errores: + + + + + StreamErrorMode::Error, el valor predeterminado, emite + diagnósticos como E_WARNING y + E_NOTICE. + + + + + StreamErrorMode::Exception lanza una + StreamException si la operación + informó de un error terminante. Los errores no terminantes no lanzan + ninguna excepción y no emiten diagnósticos. + + + + + StreamErrorMode::Silent no emite diagnósticos + ni lanza excepciones. + + + + + La opción error_store recibe un caso de + StreamErrorStore y selecciona qué errores + se conservan para stream_last_errors. Con el valor predeterminado, + StreamErrorStore::Auto, esto depende del modo de error: + + + + + + Modo de error + Errores almacenados con StreamErrorStore::Auto + + + + + StreamErrorMode::Error + Ninguno + + + StreamErrorMode::Exception + Errores no terminantes + + + StreamErrorMode::Silent + Todos los errores + + + + + + La opción error_handler es un + callable que recibe la lista de objetos + StreamError de cada operación que + informó de errores, salvo que se lance una + StreamException. + + + + stream_context_set_default rechaza estas opciones. + Deben establecerse en un contexto creado con + stream_context_create que se pase a la + función, o con el que se abrió el flujo. + + + + Consulte las opciones de contexto de flujo + para ver ejemplos de cada modo de error y de un manejador de errores. + +
+ + + + stream_clear_errors + Descarta los errores de flujo almacenados + + + + &reftitle.description; + + voidstream_clear_errors + + + + Descarta los errores que devolvería stream_last_errors. + + + Dado que los errores almacenados se conservan hasta que otra operación + almacena errores, borrarlos antes de una operación permite saber después + si dicha operación almacenó alguno. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.examples; + + Ejemplo de <function>stream_clear_errors</function> + + [ + 'error_mode' => StreamErrorMode::Silent, + ], +]); + +fopen('/nonexistent/file.txt', 'r', false, $context); +var_dump(count(stream_last_errors())); + +stream_clear_errors(); +var_dump(count(stream_last_errors())); +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + stream_last_errors + + + + + diff --git a/reference/stream/functions/stream-context-set-default.xml b/reference/stream/functions/stream-context-set-default.xml index 74a30b18d..ad0e1ebe2 100644 --- a/reference/stream/functions/stream-context-set-default.xml +++ b/reference/stream/functions/stream-context-set-default.xml @@ -1,5 +1,5 @@ - + @@ -36,7 +36,7 @@ options debe ser un array asociativo de arrays asociativos, en el formato - $arr['gestor']['opción'] = $valor. + $arr['wrapper']['option'] = $value.
@@ -52,6 +52,53 @@ + + &reftitle.errors; + + Lanza una ValueError si + options no tiene el formato + $arr['wrapper']['option'] = $value, + es decir, si uno de sus elementos no es un array o tiene una clave entera. + + + Lanza una ValueError si + options contiene una de las + opciones de gestión de errores de stream + error_mode, error_store + o error_handler. + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.6.0 + + Se añadió el parámetro opcional context. + + + + 8.0.0 + + Ahora lanza una ValueError si + options no tiene el formato esperado. + Anteriormente, se emitía un E_WARNING. + + + + + + + &reftitle.examples; diff --git a/reference/stream/functions/stream-copy-to-stream.xml b/reference/stream/functions/stream-copy-to-stream.xml index 699c6474a..cb219443d 100644 --- a/reference/stream/functions/stream-copy-to-stream.xml +++ b/reference/stream/functions/stream-copy-to-stream.xml @@ -1,6 +1,6 @@ - + @@ -16,6 +16,7 @@ resourceto intnulllength&null; intoffset0 + resourcenullcontext&null; Realiza una copia de hasta length bytes de datos @@ -70,6 +71,12 @@ + + context + + &ext.stream.context-error-handling; + + @@ -92,6 +99,12 @@ + + 8.6.0 + + Se añadió el parámetro opcional context. + + 8.0.0 diff --git a/reference/stream/functions/stream-is-local.xml b/reference/stream/functions/stream-is-local.xml index 1aed7e6f9..f8df2278d 100644 --- a/reference/stream/functions/stream-is-local.xml +++ b/reference/stream/functions/stream-is-local.xml @@ -1,6 +1,6 @@ - + @@ -13,6 +13,7 @@ boolstream_is_local resourcestringstream + resourcenullcontext&null; stream_is_local verifica si el flujo o @@ -32,6 +33,15 @@ + + context + + &ext.stream.context-error-handling; + + Solo se utiliza si stream es un &string;. + + + @@ -43,6 +53,28 @@ + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.6.0 + + Se añadió el parámetro opcional context. + + + + + + + &reftitle.examples; diff --git a/reference/stream/functions/stream-last-errors.xml b/reference/stream/functions/stream-last-errors.xml new file mode 100644 index 000000000..7c147962b --- /dev/null +++ b/reference/stream/functions/stream-last-errors.xml @@ -0,0 +1,108 @@ + + + + + + stream_last_errors + Devuelve los errores almacenados de la operación de flujo más reciente + + + + &reftitle.description; + + arraystream_last_errors + + + + Devuelve los errores que almacenó la operación de flujo más reciente que + almacenó alguno. Los errores que almacena una operación se controlan + mediante las opciones de contexto de flujo + error_store + y + error_mode. + Con las opciones predeterminadas no se almacena ningún error. + + + Los errores almacenados se reemplazan cuando una operación posterior + almacena errores. Se conservan cuando una operación posterior tiene éxito + o no almacena sus errores, y pueden descartarse con + stream_clear_errors. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Devuelve una lista de objetos StreamError en el + orden en que se informaron los errores, + o un array vacío si no hay errores almacenados. + + + + + &reftitle.examples; + + Ejemplo de <function>stream_last_errors</function> + + [ + 'error_mode' => StreamErrorMode::Silent, + ], +]); + +$stream = fopen('/nonexistent/file.txt', 'r', false, $context); +var_dump($stream); + +foreach (stream_last_errors() as $error) { + echo $error->code->name, ': ', $error->message, PHP_EOL; +} +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + stream_clear_errors + StreamError + StreamException::getErrors + + + + + + diff --git a/reference/stream/functions/stream-select.xml b/reference/stream/functions/stream-select.xml index 955885dcd..ed4e54f53 100644 --- a/reference/stream/functions/stream-select.xml +++ b/reference/stream/functions/stream-select.xml @@ -1,5 +1,5 @@ - + @@ -15,6 +15,7 @@ arraynullexcept intnullseconds intnullmicroseconds&null; + resourcenullcontext&null; stream_select acepta un array de flujos y @@ -129,6 +130,16 @@ + + context + + &ext.stream.context-error-handling; + + La advertencia emitida cuando falla la llamada al sistema subyacente no + se ve afectada por estas opciones. + + + @@ -156,6 +167,12 @@ + + 8.6.0 + + Se añadió el parámetro opcional context. + + 8.1.0 diff --git a/reference/stream/functions/stream-socket-pair.xml b/reference/stream/functions/stream-socket-pair.xml index 7929ece0c..fb55ee5b8 100644 --- a/reference/stream/functions/stream-socket-pair.xml +++ b/reference/stream/functions/stream-socket-pair.xml @@ -1,6 +1,6 @@ - + @@ -17,6 +17,7 @@ intdomain inttype intprotocol + resourcenullcontext&null; stream_socket_pair crea un par de sockets conectados @@ -64,6 +65,16 @@ + + context + + &ext.stream.context-error-handling; + + La advertencia emitida cuando no se pueden crear los sockets no se ve + afectada por estas opciones. + + + @@ -82,6 +93,28 @@ + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.6.0 + + Se añadió el parámetro opcional context. + + + + + + + &reftitle.examples; diff --git a/reference/stream/streamerror.xml b/reference/stream/streamerror.xml new file mode 100644 index 000000000..97c8ddca1 --- /dev/null +++ b/reference/stream/streamerror.xml @@ -0,0 +1,148 @@ + + + + + + La clase StreamError + StreamError + + + +
+ &reftitle.intro; + + Un objeto StreamError describe un único error + notificado por una operación de flujo. Las instancias son creadas por PHP, + son devueltas por stream_last_errors and + StreamException::getErrors y se pasan a la opción de + contexto de flujo + error_handler. + +
+ +
+ &reftitle.classsynopsis; + + + + final + readonly + StreamError + + + &Properties; + + public + StreamErrorCode + code + + + public + string + message + + + public + string + wrapperName + + + public + int + severity + + + public + bool + terminating + + +
+ +
+ &reftitle.properties; + + + code + + + El caso de StreamErrorCode que identifica el tipo de error. + + + + + message + + + El mensaje de error. Es el texto del diagnóstico que se emite + con StreamErrorMode::Error, sin el prefijo del nombre + de la función. + + + + + wrapperName + + + El nombre de la envoltura de flujo que notificó el error, + por ejemplo plainfile para los ficheros locales. + + + + + severity + + + El nivel con el que se notifica el error en el modo + StreamErrorMode::Error, + como una de las constantes + E_*, + por ejemplo E_WARNING o E_NOTICE. + + + + + terminating + + + &true; si el error puso fin a la operación y lanza una + StreamException en el modo + StreamErrorMode::Exception, &false; en caso contrario. + + + + +
+ +
+ &reftitle.seealso; + + stream_last_errors + StreamException::getErrors + + +
+ +
+ +
+ diff --git a/reference/stream/streamerrorcode.xml b/reference/stream/streamerrorcode.xml new file mode 100644 index 000000000..603c6a2ee --- /dev/null +++ b/reference/stream/streamerrorcode.xml @@ -0,0 +1,606 @@ + + + + + La enumeración StreamErrorCode + StreamErrorCode + + +
+ &reftitle.intro; + + La enumeración StreamErrorCode identifica el tipo de + error que ha notificado una operación de flujo. Está disponible en + StreamError::$code. + + + Un mismo caso puede ser notificado por distintas envolturas por + motivos diferentes; StreamError::$message + describe el fallo concreto. + +
+ +
+ &reftitle.enumsynopsis; + + + StreamErrorCode + + + None + + Sin error. + + + + + Generic + + Un error genérico. + + + + + ReadFailed + + Falló la lectura del flujo. + + + + + WriteFailed + + Falló la escritura en el flujo. + + + + + SeekFailed + + Falló el posicionamiento en el flujo. + + + + + SeekNotSupported + + El flujo no admite el posicionamiento. + + + + + FlushFailed + + Falló el volcado del flujo. + + + + + TruncateFailed + + Falló el truncamiento del flujo. + + + + + ConnectFailed + + Falló la conexión del socket. + + + + + BindFailed + + Falló la vinculación del socket a una dirección. + + + + + ListenFailed + + Falló la escucha en el socket. + + + + + AcceptFailed + + Falló la aceptación de una conexión en el socket. + + + + + NotWritable + + El flujo no admite escritura. + + + + + NotReadable + + El flujo no admite lectura. + + + + + Disabled + + La envoltura o la operación está deshabilitada por la configuración. + + + + + NotFound + + El recurso no existe. + + + + + PermissionDenied + + Permiso denegado. + + + + + AlreadyExists + + El fichero o directorio ya existe. + + + + + InvalidPath + + La ruta de acceso no es válida. + + + + + PathTooLong + + La ruta de acceso es demasiado larga. + + + + + OpenFailed + + Falló la apertura. + + + + + CreateFailed + + Falló la creación del recurso. + + + + + DupFailed + + Falló la duplicación de un descriptor de fichero. + + + + + UnlinkFailed + + Falló la eliminación del fichero. + + + + + RenameFailed + + Falló el cambio de nombre del fichero o directorio. + + + + + MkdirFailed + + Falló la creación del directorio. + + + + + RmdirFailed + + Falló la eliminación del directorio. + + + + + StatFailed + + Falló la obtención de la información del fichero. + + + + + MetaFailed + + Falló la modificación de los metadatos del fichero. + + + + + ChmodFailed + + Falló la modificación del modo del fichero. + + + + + ChownFailed + + Falló la modificación del propietario del fichero. + + + + + CopyFailed + + Falló la copia del fichero. + + + + + TouchFailed + + Falló la modificación de las fechas del fichero. + + + + + InvalidMode + + El modo de apertura no es válido. + + + + + InvalidMeta + + La opción de metadatos no es válida. + + + + + ModeNotSupported + + El modo de apertura no es compatible. + + + + + Readonly + + El recurso es de solo lectura. + + + + + RecursionDetected + + Se evitó una recursión infinita. + + + + + NotImplemented + + La envoltura no implementa la operación. + + + + + NoOpener + + La envoltura no puede abrir flujos. + + + + + PersistentNotSupported + + Los flujos persistentes no son compatibles. + + + + + WrapperNotFound + + La envoltura no existe. + + + + + WrapperDisabled + + La envoltura está deshabilitada. + + + + + ProtocolUnsupported + + El protocolo no es compatible. + + + + + WrapperRegistrationFailed + + Falló el registro de la envoltura. + + + + + WrapperUnregistrationFailed + + Falló la anulación del registro de la envoltura. + + + + + WrapperRestorationFailed + + Falló la restauración de la envoltura. + + + + + FilterNotFound + + El filtro de flujo no existe. + + + + + FilterFailed + + Falló un filtro de flujo. + + + + + CastFailed + + Falló la conversión del flujo. + + + + + CastNotSupported + + El flujo no se puede convertir al tipo solicitado. + + + + + MakeSeekableFailed + + Falló la conversión del flujo en un flujo posicionable. + + + + + BufferedDataLost + + Se perdieron datos del búfer durante una conversión. + + + + + NetworkSendFailed + + Falló el envío de datos. + + + + + NetworkRecvFailed + + Falló la recepción de datos. + + + + + SslNotSupported + + El flujo no admite el cifrado. + + + + + ResumptionFailed + + Falló la reanudación. + + + + + SocketPathTooLong + + La ruta de acceso del socket es demasiado larga. + + + + + OobNotSupported + + El flujo no admite datos fuera de banda. + + + + + ProtocolError + + Se produjo un error de protocolo. + + + + + InvalidUrl + + La URL no es válida. + + + + + InvalidResponse + + La respuesta no es válida. + + + + + InvalidHeader + + Una cabecera no es válida. + + + + + InvalidParam + + Un parámetro u opción no es válido. + + + + + RedirectLimit + + Se alcanzó el límite de redirecciones. + + + + + AuthFailed + + Falló la autenticación. + + + + + TimeOut + + Se agotó el tiempo de espera de la operación. + + + + + ArchivingFailed + + Falló el archivado. + + + + + EncodingFailed + + Falló la codificación. + + + + + DecodingFailed + + Falló la decodificación. + + + + + InvalidFormat + + El formato de los datos no es válido. + + + + + AllocationFailed + + Falló la asignación. + + + + + TemporaryFileFailed + + Falló la creación de un fichero temporal. + + + + + LockFailed + + Falló el bloqueo del flujo. + + + + + LockNotSupported + + El flujo no admite el bloqueo. + + + + + UserspaceNotImplemented + + La envoltura de usuario no implementa el método. + + + + + UserspaceInvalidReturn + + Un método de la envoltura de usuario devolvió un valor no válido. + + + + + UserspaceCallFailed + + Falló la llamada a una retrollamada de usuario. + + + +
+ +
+ &reftitle.seealso; + + StreamError + stream_last_errors + + +
+
+
+ diff --git a/reference/stream/streamerrormode.xml b/reference/stream/streamerrormode.xml new file mode 100644 index 000000000..6e11d413c --- /dev/null +++ b/reference/stream/streamerrormode.xml @@ -0,0 +1,78 @@ + + + + + La enumeración StreamErrorMode + StreamErrorMode + + +
+ &reftitle.intro; + + La enumeración StreamErrorMode especifica cómo se notifican los errores de + una operación de flujo. Es el valor de la opción de contexto de flujo + error_mode. + +
+ +
+ &reftitle.enumsynopsis; + + + StreamErrorMode + + + Error + + Los errores se notifican como diagnósticos, como E_WARNING. + Es el valor por defecto. + + + + + Exception + + Se lanza una StreamException para los + errores terminantes. + + + + + Silent + + Los errores no se notifican. + + + +
+ +
+ &reftitle.seealso; + + StreamErrorStore + + + +
+
+
+ diff --git a/reference/stream/streamerrorstore.xml b/reference/stream/streamerrorstore.xml new file mode 100644 index 000000000..6b514b5be --- /dev/null +++ b/reference/stream/streamerrorstore.xml @@ -0,0 +1,93 @@ + + + + + La enumeración StreamErrorStore + StreamErrorStore + + +
+ &reftitle.intro; + + La enumeración StreamErrorStore especifica qué errores de + una operación de flujo se almacenan para poder recuperarlos con + stream_last_errors. Es el valor de la opción de contexto de flujo + error_store. + +
+ +
+ &reftitle.enumsynopsis; + + + StreamErrorStore + + + Auto + + Los errores almacenados dependen del modo de error. + Es el valor por defecto. + + + + + None + + No se almacena ningún error. + + + + + NonTerminating + + Solo se almacenan los errores no terminantes. + + + + + Terminating + + Solo se almacenan los errores terminantes. + + + + + All + + Se almacenan todos los errores. + + + +
+ +
+ &reftitle.seealso; + + StreamErrorMode + stream_last_errors + + + +
+
+
+ diff --git a/reference/stream/streamexception.xml b/reference/stream/streamexception.xml new file mode 100644 index 000000000..47337aa83 --- /dev/null +++ b/reference/stream/streamexception.xml @@ -0,0 +1,92 @@ + + + + + + La clase StreamException + StreamException + + + +
+ &reftitle.intro; + + Se lanza una StreamException cuando una operación + de flujo notifica un error terminante y la opción de contexto de flujo + error_mode + está establecida en StreamErrorMode::Exception. + + + El mensaje de la excepción es el mensaje del primer error de la operación. + Todos los errores de la operación están disponibles mediante + StreamException::getErrors. + + + + El código de la excepción es un número interno que puede cambiar entre + versiones de PHP. Para identificar el error, utilice la propiedad + code de los + errores devueltos por StreamException::getErrors. + + +
+ +
+ &reftitle.classsynopsis; + + + + StreamException + + + + extends + Exception + + + &InheritedProperties; + + + &Methods; + + + &InheritedMethods; + + + +
+ +
+ &reftitle.seealso; + + StreamError + + + +
+ +
+ + &reference.stream.entities.streamexception; + +
+ diff --git a/reference/stream/streamexception/geterrors.xml b/reference/stream/streamexception/geterrors.xml new file mode 100644 index 000000000..f9e2992a5 --- /dev/null +++ b/reference/stream/streamexception/geterrors.xml @@ -0,0 +1,95 @@ + + + + + + StreamException::getErrors + Devuelve los errores de la operación de flujo fallida + + + + &reftitle.description; + + public arrayStreamException::getErrors + + + + Devuelve todos los errores notificados por la operación de flujo que lanzó la + excepción, tanto terminantes como no terminantes. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Devuelve una lista de objetos StreamError en el + orden en que se notificaron los errores. + + + + + &reftitle.examples; + + Ejemplo de <methodname>StreamException::getErrors</methodname> + + [ + 'error_mode' => StreamErrorMode::Exception, + ], +]); + +try { + $stream = fopen('/nonexistent/file.txt', 'r', false, $context); +} catch (StreamException $exception) { + echo $exception->getMessage(), PHP_EOL; + + foreach ($exception->getErrors() as $error) { + echo $error->wrapperName, ': ', $error->code->name, PHP_EOL; + } +} +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + stream_last_errors + + + +