From 36ec51fe267b63a9c0980e638574e4ed4bdea91a Mon Sep 17 00:00:00 2001 From: Josantonius Date: Wed, 13 Jul 2022 17:33:48 +0200 Subject: [PATCH] docs: improve documentation --- .github/lang/es-ES/README.md | 41 +++++++++++++------------ README.md | 58 ++++++++++++++++++++++-------------- 2 files changed, 57 insertions(+), 42 deletions(-) diff --git a/.github/lang/es-ES/README.md b/.github/lang/es-ES/README.md index cd183f4..1798b57 100644 --- a/.github/lang/es-ES/README.md +++ b/.github/lang/es-ES/README.md @@ -68,15 +68,15 @@ git clone https://github.com/josantonius/php-cookie.git ```php /** - * Opciones por defecto: + * Opciones: * - * domain: '' - Dominio para el que estará disponible la cookie. - * expires: 0 - Cuándo expirará la cookie. - * httpOnly: false - Si la cookie sólo estará disponible a través del protocolo HTTP. - * path: '/' - Ruta para la que estará disponible la cookie. - * raw: false - Si la cookie se enviará como una cadena sin procesar. - * sameSite: null - Impone el uso de una política samesite laxa o estricta. - * secure: false - Si la cookie sólo estará disponible a través del protocolo HTTPS. + * domain: Dominio para el que estará disponible la cookie. + * expires: Cuándo expirará la cookie. + * httpOnly: Si la cookie sólo estará disponible a través del protocolo HTTP. + * path: Ruta para la que estará disponible la cookie. + * raw: Si la cookie se enviará como una cadena sin procesar. + * sameSite: Impone el uso de una política samesite laxa o estricta. + * secure: Si la cookie sólo estará disponible a través del protocolo HTTPS. * * Estos ajustes se utilizarán para crear y eliminar cookies. */ @@ -100,7 +100,11 @@ para conocer los formatos de fecha y hora admitidos. ### Establece una cookie por nombre ```php -$cookie->set(string $name, mixed $value, null|int|string|DateTime $expires = null): void; +$cookie->set( + string $name, + mixed $value, + null|int|string|DateTime $expires = null +): void ``` **@throws** `CookieException` si las cabeceras ya han sido enviadas. @@ -112,7 +116,10 @@ $cookie->set(string $name, mixed $value, null|int|string|DateTime $expires = nul Si las cookies existen se sustituyen, si no existen se crean. ```php -$cookie->replace(array $data, null|int|string|DateTime $expires = null): void +$cookie->replace( + array $data, + null|int|string|DateTime $expires = null +): void ``` **@throws** `CookieException` si las cabeceras ya han sido enviadas. @@ -382,16 +389,13 @@ se utilizará este en lugar del valor de **_expires_** establecido en las opcion expires: 'now +1 minute' ); - $cookie->set('foo', 'bar'); // Esta cookie expirará en 1 minuto + $cookie->set('foo', 'bar'); // Caduca en 1 minuto - $cookie->set('bar', 'foo', 'now +8 days'); // Esta cookie expirará en 8 días + $cookie->set('bar', 'foo', 'now +8 days'); // Caduca en 8 días - $cookie->replace(['foo' => 'bar']); // Estas cookies expirarán en 1 minuto + $cookie->replace(['foo' => 'bar']); // Caduca en 1 minuto - $cookie->replace( // Estas cookies expirarán en 1 hora - ['foo' => 'bar'], - time() + 3600 - ); + $cookie->replace(['foo' => 'bar'], time() + 3600); // Caduca en 1 hora ``` - Si el parámetro **expires** pasado en las opciones es una cadena de fecha/hora, @@ -402,8 +406,7 @@ se formateará cuando se utiliza el método `set` o `replace` y no cuando se est expires: 'now +1 minute', // Todavía no se formateará como tiempo unix ); - $cookie->set('foo', 'bar'); // Se formateará en este momento - // y expirará 1 minuto después de la creación de esta cookie + $cookie->set('foo', 'bar'); // Se formateará ahora y expirará en 1 minuto ``` ## Tests diff --git a/README.md b/README.md index 1f1af45..53cb476 100644 --- a/README.md +++ b/README.md @@ -70,15 +70,15 @@ Available methods in this library: ```php /** - * Default options: + * Cookie options: * - * domain: '' - Domain for which the cookie is available. - * expires: 0 - The time the cookie will expire. - * httpOnly: false - If cookie will only be available through the HTTP protocol. - * path: '/' - Path for which the cookie is available. - * raw: false - If cookie will be sent as a raw string. - * sameSite: null - Enforces the use of a Lax or Strict SameSite policy. - * secure: false - If cookie will only be available through the HTTPS protocol. + * domain: Domain for which the cookie is available. + * expires: The time the cookie will expire. + * httpOnly: If cookie will only be available through the HTTP protocol. + * path: Path for which the cookie is available. + * raw: If cookie will be sent as a raw string. + * sameSite: Enforces the use of a Lax or Strict SameSite policy. + * secure: If cookie will only be available through the HTTPS protocol. * * These settings will be used to create and delete cookies. */ @@ -102,7 +102,11 @@ for supported date and time formats. ### Sets a cookie by name ```php -$cookie->set(string $name, mixed $value, null|int|string|DateTime $expires = null): void; +$cookie->set( + string $name, + mixed $value, + null|int|string|DateTime $expires = null +): void ``` **@throws** `CookieException` if headers already sent. @@ -114,7 +118,10 @@ $cookie->set(string $name, mixed $value, null|int|string|DateTime $expires = nul If cookies exist they are replaced, if they do not exist they are created. ```php -$cookie->replace(array $data, null|int|string|DateTime $expires = null): void +$cookie->replace( + array $data, + null|int|string|DateTime $expires = null +): void ``` **@throws** `CookieException` if headers already sent. @@ -249,19 +256,28 @@ Cookie::set('foo', 'bar', new DateTime('now +1 hour')); Without modifying the expiration time: ```php -$cookie->replace(['foo' => 'bar', 'bar' => 'foo']); +$cookie->replace([ + 'foo' => 'bar', + 'bar' => 'foo' +]); ``` Modifying the expiration time: ```php -$cookie->replace(['foo' => 'bar', 'bar' => 'foo'], time() + 3600); +$cookie->replace([ + 'foo' => 'bar', + 'bar' => 'foo' +], time() + 3600); ``` [Using the facade](#using-the-facade): ```php -Cookie::replace(['foo' => 'bar', 'bar' => 'foo'], time() + 3600); +Cookie::replace([ + 'foo' => 'bar', + 'bar' => 'foo' +], time() + 3600); ``` ### - Gets a cookie by name @@ -384,16 +400,13 @@ it will be taken instead of the **expires** value set in the cookie options. expires: 'now +1 minute' ); - $cookie->set('foo', 'bar'); // This cookie will expire in 1 minute + $cookie->set('foo', 'bar'); // Expires in 1 minute - $cookie->set('bar', 'foo', 'now +8 days'); // This cookie will expire in 8 days + $cookie->set('bar', 'foo', 'now +8 days'); // Expires in 8 days - $cookie->replace(['foo' => 'bar']); // This cookies will expire in 1 minute + $cookie->replace(['foo' => 'bar']); // Expires in 1 minute - $cookie->replace( // This cookies will expire in 1 hour - ['foo' => 'bar'], - time() + 3600 - ); + $cookie->replace(['foo' => 'bar'], time() + 3600); // Expires in 1 hour ``` - If the **expires** parameter passed in the options is a date/time string, @@ -404,8 +417,7 @@ it is formatted when using the `set` or `replace` method and not when setting th expires: 'now +1 minute', // It will not be formatted as unix time yet ); - $cookie->set('foo', 'bar'); // It is will formatted now - // and will expire 1 minute after this cookie is created + $cookie->set('foo', 'bar'); // It is will formatted now and expires in 1 minute ``` ## Tests @@ -456,7 +468,7 @@ composer tests - [ ] Improve tests - [ ] Improve documentation - [ ] Improve English translation in the README file -- [ ] Refactor code for disabled code style rules. See [phpmd.xml](phpmd.xml) and [phpcs.xml](phpcs.xml) +- [ ] Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml) ## Changelog