Skip to content

Commit

Permalink
docs: improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@josantonius
josantonius committed Jul 13, 2022
1 parent 64bbf88 commit 36ec51f
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 42 deletions.
41 changes: 22 additions & 19 deletions .github/lang/es-ES/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down
58 changes: 35 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 36ec51f

Please sign in to comment.