Skip to content

6. Escopos de dados

Uma aplicação web atende muitos usuários ao mesmo tempo, e cada usuário faz inúmeras requisições. Os dados podem, portanto, ser compartilhados em vários níveis, conhecidos como escopo:

  • aplicação (escopo de): os dados são compartilhados por todos os usuários durante todo o tempo de vida da aplicação (a lista de médicos, por exemplo);
  • requisição (escopo de): os dados existem apenas durante uma requisição (o modelo de uma view, o usuário logado conforme identificado naquela requisição);
  • sessão (escopo de): os dados são específicos de um usuário e devem persistir de uma requisição para a seguinte (o idioma selecionado, um carrinho de compras);
  • cliente (escopo de): dados armazenados no próprio navegador, em um cookie.

Em [PHP], esses escopos se comportam de maneira particular porque a aplicação é reconstruída a cada requisição (exemplo 01): nada sobrevive na memória de uma requisição para a seguinte. Qualquer dado que precise durar mais que uma única requisição é, portanto, armazenado fora do [PHP]: no cache, em um banco de dados, em arquivos ou no lado do cliente. Essa é a chamada arquitetura “shared-nothing”: cada requisição é processada isoladamente por um processo que não compartilha nada com os que processam outras requisições. Essa abordagem tem vantagens significativas: um erro afeta apenas uma única requisição, nenhum dado vaza de um usuário para outro, e é possível executar vários servidores idênticos atrás de um balanceador de carga, desde que compartilhem o mesmo cache e o mesmo banco de dados.

No [Laravel], cada escopo tem seu próprio contêiner:

Escopo
Contêiner
Duração
aplicação
o cache ([Cache] front end, exemplo 20), ou o banco de dados
a duração escolhida, ou ilimitada
requisição
os objetos do contêiner (um singleton existe apenas para uma requisição), os atributos da requisição (exemplo 12)
o processamento de uma requisição
sessão
a sessão ([$request->session()], [session()]), armazenada pelo servidor e recuperada por meio de um cookie
Período de inatividade padrão de 2 horas ([SESSION_LIFETIME])
cliente
um cookie ([withCookie], exemplo 22), criptografado por padrão
a duração especificada para o cookie

A sessão do [Laravel] é uma sessão mantida pelo servidor, como as do [Java] ([JSESSIONID]) ou do [PHP] clássico ([PHPSESSID]): seus dados ficam armazenados no servidor (um arquivo por sessão, com a configuração dos nossos exemplos), e o navegador guarda apenas o identificador em um cookie criptografado (exemplo 20). Isso difere do [Flask], cuja sessão inteira é armazenada em um cookie assinado no lado do cliente.

6.1. Exemplo 23: Escopos

23-scopes/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── ScopesController.php
│   └── Services/
│       ├── CounterService.php
│       └── RequestInfo.php
├── resources/
│   └── views/
│       └── scopes/
│           └── scopes.blade.php
└── ...

6.1.1. Os objetos: app/Services/CounterService.php e RequestInfo.php

<?php
// app/Services/CounterService.php: escopo de APLICAÇÃO, um contador compartilhado por
// todas as requisições de todos os usuários, armazenado no cache (veja o exemplo 20)

namespace App\Services;

use Illuminate\Support\Facades\Cache;

class CounterService
{
    // um número a mais sob a chave [$key]; o cache "file" não incrementa um
    // número de forma atômica: um lock protege a leitura e a escrita
    public static function next(string $key): int
    {
        return Cache::lock("$key-lock", 10)->block(5, function () use ($key) {
            $value = Cache::get($key, 0) + 1;
            Cache::forever($key, $value);
            return $value;
        });
    }

    public function increment(): int
    {
        return self::next('visits');
    }
}
  • Linhas 13–20: um contador de escopo de aplicação: um número armazenado no cache sob uma chave e incrementado em 1 a cada chamada. O cache oferece um método [Cache::increment], mas com o store “file” usado em nossos exemplos ele não é atômico: lê o valor, incrementa e depois grava, e duas requisições concorrentes poderiam ler o mesmo valor, resultando em uma visita perdida. Um lock (exemplo 20) protege, portanto, tanto a leitura quanto a gravação. (Com um store como [Redis] ou um banco de dados, [Cache::increment] é atômico e o lock é desnecessário.) A função retorna o valor do lock, que é o mesmo valor retornado pela função que ele protege;
  • linhas 22–25: o contador de visitas.
<?php
// app/Services/RequestInfo.php: escopo de REQUISIÇÃO, as informações de uma requisição

namespace App\Services;

class RequestInfo
{
    public readonly int $number;

    public readonly string $start;

    public function __construct()
    {
        // um número por OBJETO criado, obtido de um contador compartilhado por todas as requisições
        $this->number = CounterService::next('instances');
        // a hora, com seus milissegundos (v)
        $this->start = now()->format('H:i:s.v');
    }
}
  • linhas 8–10: propriedades declaradas como [readonly] uma a uma (em vez de a classe inteira): elas só podem ser atribuídas uma vez, pelo construtor;
  • linhas 12–18: informações de escopo de requisição: um número, derivado de um contador compartilhado por todas as requisições (o contador da classe anterior, sob outra chave), e a hora da requisição. A função [now()] retorna a hora atual como uma data [Carbon]; o formato [v] especifica os milissegundos.

6.1.2. Configuração: bootstrap/app.php

<?php
// bootstrap/app.php: a aplicação do exemplo 23

use App\Services\CounterService;
use App\Services\RequestInfo;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // a rota que serve o Bootstrap (veja o exemplo 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // o cookie [myVisits] não é criptografado (os outros são)
        $middleware->encryptCookies(except: ['myVisits']);
    })
    ->withExceptions()
    // um único objeto de cada classe durante o tratamento de uma requisição
    ->withSingletons([CounterService::class])
    ->withScopedSingletons([RequestInfo::class])
    ->create();
  • Linha 18: o cookie [myVisits] não é criptografado; todos os outros são (exemplo 22);
  • Linhas 22–23: os dois serviços são registrados no contêiner. [withSingletons] (exemplo 06): um único objeto, criado na primeira requisição. [withScopedSingletons]: um único objeto por requisição. Em um [PHP]padrão, os dois são equivalentes, pois cada requisição reconstrói a aplicação e seu contêiner. A diferença aparece com o [Laravel Octane], um servidor de aplicação que mantém a aplicação na memória de uma requisição para a seguinte para melhorar o desempenho: um singleton é compartilhado por todas as requisições, enquanto um singleton “scoped” é recriado a cada uma. Declarar o escopo desejado garante que o código esteja correto nos dois casos.

6.1.3. O controller: app/Http/Controllers/ScopesController.php

<?php
// app/Http/Controllers/ScopesController.php: os quatro escopos de dados

namespace App\Http\Controllers;

use App\Services\CounterService;
use App\Services\RequestInfo;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class ScopesController
{
    // os dois objetos são fornecidos pelo container (veja bootstrap/app.php)
    public function display(Request $request, CounterService $counter, RequestInfo $info): Response
    {
        // APLICAÇÃO: o contador compartilhado
        $total = $counter->increment();
        // SESSÃO: dados específicos DESTE navegador, mantidos pelo SERVIDOR
        // (um arquivo de storage/framework/sessions), reencontrados graças ao cookie de sessão
        $sessionVisits = $request->session()->increment('visits');
        // CLIENTE: dados mantidos pelo NAVEGADOR em cookies,
        // reenviados ao servidor a cada requisição; um em texto claro, o outro criptografado
        $myVisits = (int) $request->cookie('myVisits') + 1;
        $myEncryptedVisits = (int) $request->cookie('myEncryptedVisits') + 1;
        return response()->view('scopes.scopes', [
            'total' => $total, 'instance' => $info->number,
            'sessionVisits' => $sessionVisits, 'myVisits' => $myVisits,
            'myEncryptedVisits' => $myEncryptedVisits,
        ])->withCookie(cookie('myVisits', $myVisits))
            ->withCookie(cookie('myEncryptedVisits', $myEncryptedVisits));
    }
}
  • linha 14: a action recebe a requisição e os dois serviços, fornecidos pelo contêiner;
  • linha 17: o escopo de aplicação;
  • linha 20: o escopo de sessão. [$request->session()] retorna a sessão do usuário; seu método [increment] incrementa em 1 o valor de uma chave (ou o define como 0 se ela não existir) e retorna o novo valor. Um valor é lido com [get('visits')] e gravado com [put('visits', 3)]; a função [session('visits')] é um atalho para leitura. [Laravel] salva a sessão ao final da requisição (o middleware [StartSession] do grupo [web]);
  • linhas 23–24: o escopo de cliente, com dois cookies. Seus valores são strings fornecidas pelo navegador e, portanto, podem estar ausentes ou ser inválidos: a conversão [(int)] retorna 0 para [null] ou para um texto que não seja um número;
  • Linhas 25–30: para definir um cookie, é preciso o objeto de resposta: [response()->view(...)] o constrói a partir da view (exemplo 13), e então [withCookie] adiciona os cookies a ele. Sem um tempo de expiração, um cookie dura até o navegador ser fechado (é um cookie “de sessão”, no sentido definido pelos navegadores).

6.1.4. A view: resources/views/scopes/scopes.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Scopes</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
</head>
<body>
  <div class="container py-3">
    <h1 class="h3">The scopes of data</h1>
    {{-- @inject: an object requested from the container, from the view; during the SAME
         request, it is the same object as the one of the action --}}
    @inject('info', 'App\Services\RequestInfo')
    <ul>
      <li>application: {{ $total }} visit(s) to the site, all browsers combined</li>
      <li>request: object no. {{ $instance }} (no. {{ $info->number }} in the view),
        request received at {{ $info->start }}</li>
      <li>session: {{ $sessionVisits }} visit(s) from this browser ({{ session('visits') }} in the view)</li>
      <li>client: {{ $myVisits }} visit(s) from this browser (clear-text cookie),
        {{ $myEncryptedVisits }} (encrypted cookie)</li>
    </ul>
  </div>
</body>
</html>
  • Linha 13: a diretiva [@inject] solicita um objeto ao contêiner, de dentro da view, e o armazena em uma variável (aqui, [$info]). Durante a mesma requisição, este é o mesmo objeto [RequestInfo] que o da action: a view exibe seu número, que deve ser o recebido da action;
  • Linha 18: a sessão também é acessível nas views.

6.1.5. Execução

Após algumas visitas em um navegador:

Image

Vamos acompanhar as requisições com o [curl], que funciona como um primeiro navegador, armazenando seus cookies no arquivo [a.txt]:

curl -i -c a.txt -b a.txt http://localhost:8000/
HTTP/1.1 200 OK
Set-Cookie: myVisits=1; path=/; httponly; samesite=lax
Set-Cookie: myEncryptedVisits=eyJpdiI6InFOdXY5QmhoSlNCTWx4Q0VmN1lDSUE9PSIsInZhbHVlIjoiNm1GckpjQ3JK...; path=/; httponly; samesite=lax
Set-Cookie: XSRF-TOKEN=eyJpdiI6Im5IcHgvN2RRWiswNEZkMFRrUHBkOEE9PSIsInZhbHVlIjoiMTk1eElxemZz...; expires=...; Max-Age=7200; path=/; samesite=lax
Set-Cookie: example23_session=eyJpdiI6IjVEbjh1V2toeTdCdUFhSDdWWkV3ZHc9PSIsInZhbHVlIjoiK1J5SVNi...; expires=...; Max-Age=7200; path=/; httponly; samesite=lax
...
      <li>application: 1 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 1 (no. 1 in the view),
        request received at 16:19:05.722</li>
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1 visit(s) from this browser (clear-text cookie),
        1 (encrypted cookie)</li>
...

A resposta define quatro cookies. O primeiro, [myVisits], contém o valor em texto simples. O segundo, [myEncryptedVisits], contém o mesmo valor, criptografado: a parte visível é uma string codificada em Base64 (JSON), que contém o vetor de inicialização da criptografia ([iv]), o valor criptografado ([value]) e um código de autenticação ([mac]), que garante que o valor não foi alterado. Os dois últimos são da sessão e da proteção anti-CSRF (exemplo 20). Uma segunda visita, com os mesmos cookies:

curl -i -c a.txt -b a.txt http://localhost:8000/
...
Set-Cookie: myVisits=2; path=/; httponly; samesite=lax
...
      <li>application: 2 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 2 (no. 2 in the view),
        request received at 16:19:05.922</li>
      <li>session: 2 visit(s) from this browser (2 in the view)</li>
      <li>client: 2 visit(s) from this browser (clear-text cookie),
        2 (encrypted cookie)</li>
...

Um segundo “navegador”, com seu próprio arquivo de cookies, inicialmente vazio:

curl -c b.txt -b b.txt http://localhost:8000/
1
2
3
4
5
6
      <li>application: 3 visit(s) to the site, all browsers combined</li>
      <li>request: object no. 3 (no. 3 in the view),
        request received at 16:19:06.027</li>
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1 visit(s) from this browser (clear-text cookie),
        1 (encrypted cookie)</li>

O contador da aplicação continuou a contar; a sessão e os cookies do segundo navegador recomeçam em 1. Cada requisição teve seu próprio objeto [RequestInfo], e em cada uma delas a action e a view foram as mesmas. Por fim, um usuário malicioso forja seus próprios cookies: 1.000 visitas em [myVisits], 999 em [myEncryptedVisits] e um ID de sessão de sua própria invenção:

curl -b "myVisits=1000;myEncryptedVisits=999;example23_session=abc" http://localhost:8000/
1
2
3
4
5
      <li>application: 4 visit(s) to the site, all browsers combined</li>
      ...
      <li>session: 1 visit(s) from this browser (1 in the view)</li>
      <li>client: 1001 visit(s) from this browser (clear-text cookie),
        1 (encrypted cookie)</li>

O cookie não criptografado foi aceito como está: 1.001 visitas. O cookie [myEncryptedVisits], porém, não pôde ser descriptografado: o [Laravel] o ignorou, como se estivesse ausente. O mesmo vale para o cookie de sessão: o usuário não pode escolher a sessão de outro usuário e recebe uma nova. Essa é a diferença fundamental entre um cookie comum e um cookie criptografado. Guardemos a regra: os dados vindos do cliente só são confiáveis se forem protegidos pelo servidor (criptografados, como aqui, ou assinados, como o token do capítulo sobre autenticação); dados que não têm nada a esconder e cujo valor é verificado pelo servidor (o idioma no exemplo 22) podem permanecer em texto simples.