Usuário (PT-BR)

O framework utiliza algumas nomenclaturas em inglês por padrão. Esta seção mostra como adaptar as referências relacionadas a usuários para português quando a aplicação utilizar uma convenção PT-BR.

O que existe de fato no repositório

Esta página descreve o código da versão documentada, não uma implementação presumida de outro framework. A entidade atual é App\Models\User, mapeada explicitamente para a tabela users. Ela contém name, email, password, role, active, phone, avatar e preferences; autentica com authenticate(), faz hash da senha em createWithHash() e atualiza senha por updatePassword().

Há autenticação Web por sessão/cookie e uma API própria versionada em /api/v1, com token Bearer. A API atual oferece login, logout, identidade do token e leitura paginada/individual de usuários; não há endpoints de criação, atualização ou exclusão de usuários. O fluxo Bearer é implementado pelo próprio projeto com token aleatório e hash SHA-256, não por uma dependência OAuth/JWT de terceiros; o texto claro é retornado no momento da emissão e somente o hash é persistido. Há requests de exemplo para usuários, mas isso não registra rotas nem cria um CRUD.

O Model base não implementa métodos ORM como belongsTo() ou hasMany(). O vínculo existente entre token e usuário é uma foreign key SQL, e a aplicação resolve o usuário explicitamente pelo Repository. Não existe config/auth.php; a seleção de Model é feita por Auth::setUserModel().

Conversões e classificação

A coluna PT-BR abaixo descreve uma escolha possível, não uma substituição automática. Mantenha coerentes os identificadores PHP, colunas e parâmetros HTTP que participam do mesmo fluxo.

Classificação prática

Arquivos que podem ser adaptados

Os caminhos desta tabela existem no projeto analisado. “Pode” significa que a aplicação pode adotar o nome PT-BR se atualizar os dependentes indicados; não significa que o arquivo tenha de ser alterado para traduzir a interface.

Os middlewares Web AuthMiddleware, GuestMiddleware e RoleMiddleware consultam Framework\Auth\Auth; não apontam para a classe User diretamente. Não precisam ser renomeados para que o Model passe a se chamar Usuario. O middleware ApiAuthMiddleware, ao contrário, resolve o token e o Repository de usuário explicitamente.

Banco de dados e migrations

O banco configurado é MySQL. A migration 0001_01_01_100000_create_users_table.php cria users, sua PK id, campos de autenticação/perfil, colunas de auditoria, índices uniq_users_email, idx_users_active e idx_users_role. A migration 0001_01_01_100002_add_remember_token_expires_at_to_users_table.php adiciona remember_token_expires_at à tabela users. 0001_01_01_100003_create_api_tokens_table.php cria api_tokens.user_id como INT UNSIGNED, FK para users.id com nome gerado fk_api_tokens_user_id e exclusão em cascata; o índice é idx_api_tokens_user_id.

A migration 0001_01_01_100001_create_redefinicoes_senha_table.php cria a tabela redefinicoes_senha, já nomeada em português. O fluxo usa email, token, expira_em e usado; não há nela uma FK user_id. Ela não precisa ser renomeada para adaptar a entidade.

Projeto ainda não migrado

Se nenhuma migration foi aplicada e o banco é descartável, você pode ajustar as migrations originais antes da primeira execução. Mude coerentemente a tabela no create, a migration de remember-me, o alvo da FK de api_tokens, o seeder e as regras de validação. Se também traduzir colunas, acompanhe o Model, Auth, Services, Repositories, Requests, Views e Resources. Depois confira o SQL gerado e teste uma migração limpa. O nome histórico do arquivo pode ser padronizado enquanto ainda não existe histórico; não é necessário que o nome do arquivo repita o nome da tabela para o SQL funcionar.

Projeto com migrations aplicadas / produção

Não edite migrations já aplicadas para simular uma renomeação: o histórico registrado não representa mais a estrutura que foi realmente implantada. Crie uma nova migration, faça backup, teste em cópia e planeje a implantação da aplicação junto com a mudança de esquema. Em MySQL, DDL pode fazer commit implícito; não trate várias instruções como rollback atômico.

O Schema implementado fornece create(), table(), drop() e dropIfExists(); Blueprint adiciona/remova colunas, mas não expõe renameTable(), renameColumn() ou dropForeign(). Para DDL estático, a via existente é Database::getInstance()->execMigration($sql), que chama PDO exec() e não aceita bindings. Use apenas SQL fixo, revisado e controlado — nunca concatene entrada de usuário.

Exemplo ilustrativo de up() para renomear a tabela e a FK de token preservando as linhas. Ele pressupõe o schema atual e os nomes de constraint mostrados acima; inspecione o banco real antes de usar:

use Framework\Database\Database;

public function up(): void
{
    $db = Database::getInstance();
    $db->execMigration('ALTER TABLE api_tokens DROP FOREIGN KEY fk_api_tokens_user_id');
    $db->execMigration('RENAME TABLE users TO usuarios');
    $db->execMigration('ALTER TABLE api_tokens CHANGE COLUMN user_id usuario_id INT UNSIGNED NOT NULL');
    $db->execMigration('ALTER TABLE api_tokens ADD CONSTRAINT fk_api_tokens_usuario_id FOREIGN KEY (usuario_id) REFERENCES usuarios(id) ON DELETE CASCADE ON UPDATE RESTRICT');
}

O down() precisa executar a sequência inversa: remover fk_api_tokens_usuario_id, renomear a coluna para user_id, renomear usuarios para users e recriar fk_api_tokens_user_id apontando a users(id). Antes do deploy, confirme a sintaxe de rename suportada pela versão do MySQL do ambiente e valide índices/constraints existentes. O índice pode conservar o nome antigo sem mudar a funcionalidade; renomeá-lo é uma decisão separada.

Models e relacionamentos

O Model atual declara $table = 'users', $fillable, $hidden, timestamps e soft delete. O Model base não infere uma tabela a partir da classe e não oferece relações ORM; cada Repository expressa as consultas e a FK vive no banco. Se criar a classe Usuario, declare a tabela explicitamente.

namespace App\Models;

use Framework\Database\Model;

class Usuario extends Model
{
    // Escolha conservadora: classe em português, schema existente preservado.
    protected string $table = 'users';

    // Preserve os campos e métodos exigidos pelo fluxo de autenticação.
    // Copie/revise também $fillable, $hidden, $timestamps, $softDelete,
    // findByEmail(), authenticate(), createWithHash() e updatePassword().
}

Arquivo de destino proposto: app/Models/Usuario.php não existe no projeto analisado; este exemplo mostra o arquivo que você criaria/renomearia a partir de app/Models/User.php.

Esse é um recorte para demonstrar o mapeamento, não um Model completo pronto para substituir User: o scaffold make:model não copia os métodos específicos de autenticação. Ao criar o arquivo manualmente ou pelo CLI, mantenha o namespace PSR-4, o nome da classe e o arquivo alinhados e rode composer dump-autoload quando necessário.

Se você também renomear campos do banco, o mapeamento precisa ser explícito: por exemplo, um campo interno nome não será encontrado por código que ainda lê $user->name. Preserve identificador id, e-mail, papel e estado ativos enquanto as APIs atuais do Auth dependem deles, ou atualize deliberadamente cada contrato que os consulta.

Autenticação, sessão e middleware

Framework\Auth\Auth aceita qualquer Model configurado que implemente authenticate(string $email, string $password). attempt() instancia o Model, chama esse método e, em sucesso, loginUser() guarda user_id, user_role e o objeto seguro user na sessão. check() revalida com findById() e active; outras partes leem id, role e email. Mantenha essas propriedades ou altere seus consumidores de forma coordenada.

Para escolher Usuario, a chamada pode ser colocada em bootstrap/app.php depois do autoload Composer e antes de Auth::recoverFromCookie() (antes do primeiro uso do Auth):

\Framework\Auth\Auth::setUserModel(\App\Models\Usuario::class);

Isso troca o Model instanciado por attempt(), check() e pela montagem dos campos ocultos da sessão. Não troca automaticamente a classe usada diretamente por AuthApiController ou AuthController, não renomeia as chaves de sessão e não torna configurável o SQL de remember-me em Framework\Auth\Auth. A recuperação por cookie também lê diretamente a tabela users.

Os identificadores Auth::user(), Auth::id(), Auth::role(), o helper global user() e o método protegido Controller::user() fazem parte dos pontos de uso do framework/app. Não é preciso traduzi-los para exibir “Usuário” na tela. Se adicionar aliases como usuario(), mantenha os antigos durante a migração dos consumidores.

API, Resources e contratos externos

A API é uma interface externa separada das rotas Web. Em routes/api.php, a versão /api/v1 registra POST /auth/login, POST /auth/logout, GET /auth/me, GET /users e GET /users/{id} (além de OPTIONS de preflight). As rotas de usuários são protegidas por ApiAuthMiddleware; o grupo aplica CORS e rate limit. A mudança de nome de classe PHP pode preservar as URLs; mudar /users para /usuarios altera uma URL pública e exige atualização coordenada dos clientes.

AuthApiController instancia diretamente App\Models\User, emite o token e inclui a chave JSON user. UserApiController usa UserRepository e converte resultados com UserResource. O Resource expõe id, name, email, role, active e created_at; não expõe senha, remember token nem user_id. Por isso, traduzir o Model não obriga a mudar o JSON.

Resources: estrutura interna e JSON público

app/Http/Resources/UserResource.php estende ApiResource e transforma o objeto para uma lista controlada. O nome da propriedade interna e o nome enviado ao consumidor são decisões separadas:

Em AuthApiController, a resposta de login envolve o Resource na propriedade data.user; /auth/me devolve o Resource em data, e os endpoints de lista/detalhe também serializam Resources. Mudar apenas o nome da classe Resource é interno se seus consumidores PHP forem atualizados; mudar as chaves expostas é alteração de contrato.

Controllers afetados

• app/Http/Controllers/Api/AuthApiController.php: instancia App\Models\User diretamente no login e usa UserResource no login/me. Atualize Model/Resource ali; setUserModel() não intercepta essa instância.
• app/Http/Controllers/Api/UserApiController.php: depende de UserRepository e UserResource; as duas ações implementadas são listagem e detalhe, não CRUD. Atualize o alvo em routes/api.php se renomear a classe.
• app/Http/Controllers/Web/AuthController.php: usa User diretamente em recuperação/reset e delega login/registro a AuthService. Atualize instâncias/imports e mantenha o fluxo RedefinicaoSenha.
• app/Http/Controllers/Web/DashboardController.php: passa $this->user() para a View; não instancia User. Se atributos internos mudarem, confira a View e BaseController.

Não há um Controller Web UserController neste projeto nem rota de registro de usuário pela API. Não crie a impressão de que os Requests de escrita estão conectados a actions existentes.

{
  "success": true,
  "message": "Login realizado com sucesso.",
  "data": {
    "token": "<token-em-texto-claro-uma-vez>",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "Maria",
      "email": "maria@example.com",
      "role": "member",
      "active": true,
      "created_at": "..."
    }
  }
}

Se o contrato permitir mudar data.user para data.usuario ou name para nome, documente e versione a alteração. Frontends, aplicativos móveis, integrações, testes e documentação externa que leem as chaves antigas podem falhar. Uma estratégia compatível é manter os nomes públicos e mapear os novos nomes internos no Resource.

Antes da mudança, confira também o guia da API: Requests e Resources existem, mas não substituem rotas implementadas. A API atual não tem endpoint de registro nem CRUD de usuários; não presuma que StoreUserRequest ou UpdateUserRequest os habilitem.

Requests, validação e campos HTTP

Um rótulo visível pode ser traduzido sem alterar o nome técnico do campo. No cadastro/login Web, resources/views/auth/register.php e resources/views/auth/login.php enviam name, email, password e password_confirmation; RegisterRequest sanitiza/valida esses mesmos nomes e AuthService os transforma em colunas. Se trocar name por nome no formulário, atualize o Request, suas regras e mensagens, a sanitização, o Controller/Service e o mapeamento do banco. A validação de e-mail também consulta users.

Services e Repositories

• Repository: UserRepository configura User::class, busca por email, filtra active e pesquisa por name/email. Se renomear a classe ou colunas, atualize a propriedade $modelClass e cada consulta.
• Service: AuthService recebe UserRepository, registra campos name/email/password/role/active e pode devolver user_id. Atualize tipos, chaves e consumidores internos; não confunda o array de retorno do Service com JSON público.

Middleware de autenticação

• Token e middleware: ApiToken/ApiTokenRepository armazenam user_id em api_tokens; ApiAuthMiddleware lê esse campo e procura o usuário por ID. A tabela pode receber usuario_id somente se migration, fillable, model, middleware e queries mudarem juntos.
• Contexto de API: Framework\Http\Api\ApiAuthContext oferece user(), id() e token() para a requisição atual. Preserve esses nomes enquanto Controllers API os chamarem.
• Autorização: RoleMiddleware compara valores como admin com a role devolvida por Auth. Traduzir rótulos não traduz o valor; se mudar role ou seus valores para perfil/administrador, atualize configuração/rotas, seed e todos os testes. O framework não fornece ACL de recursos completa.

Essas camadas são instanciadas explicitamente no código atual; não há container DI automático que resolva nomes antigos por você. Consulte Services, Repositories e Middleware.

Views e apresentação

Os textos visíveis de autenticação já são majoritariamente portugueses. Em login.php, por exemplo, o rótulo mostra “E-mail”, mas o campo é name="email"; em register.php, o rótulo mostra “Nome completo” enquanto o formulário envia name="name". Mantenha o atributo name compatível com Request/Controller; traduzir o label não muda o payload.

O dashboard e os componentes resources/views/dashboard/index.php, resources/views/components/sidebar.php e resources/views/components/topbar.php chamam o helper user() e leem name/email. Se o objeto passar a expor nome, ajuste esses pontos ou mapeie os campos no Model/DTO. resources/views/auth/forgot.php e resources/views/auth/reset.php usam e-mail/token e os campos de reset password/confirm; preserve a compatibilidade com ResetPasswordRequest antes de renomear campos.

É seguro traduzir rótulos, mensagens, título “Usuário” e texto de ajuda de forma independente. Na view de cadastro há também o placeholder textual “Seu name completo”; se desejar, corrija esse texto para “Seu nome completo” sem mudar name="name".

Rotas e URLs

As rotas Web em routes/web.php são de autenticação (/auth/login, /auth/register, recuperação/logout) e dashboard; não existe ali um recurso Web /users. As rotas API são escritas explicitamente em routes/api.php. Alterar apenas o nome de Controller não exige alterar o caminho; alterar caminho, nome de rota ou prefixo exige atualizar links, CORS/preflight, consumidores e documentação. O CLI de geração não registra automaticamente uma rota.

Se adotar /api/v1/usuarios, mantenha a versão (v1) e faça inventário dos clientes. Para uma mudança incompatível com consumidores já publicados, prefira planejar uma versão nova ou uma janela de compatibilidade em vez de trocar silenciosamente a URL.

CLI, stubs e bibliotecas externas

Os geradores aceitam nomes escolhidos pelo projeto. php mvc make:model Usuario cria app/Models/Usuario.php e, pela pluralização simples do CLI, sugere a tabela usuarios; edite $table para users se quiser preservar o schema atual. O stub genérico não traz os métodos authenticate(), findByEmail() e updatePassword() do Model de usuário existente. make:repository usa o nome do Model para gerar a referência; revise-a e confira os campos sugeridos pelo stub.

make:api-controller, make:api-request e make:api-resource não contêm um contrato obrigatório de User e não registram automaticamente as rotas. O Controller gerado é scaffold para completar, não prova de endpoint funcional. O gerador de Seeder escreve um arquivo selecionável pelo CLI; UserSeeder.php existente é código próprio e contém SQL direto para users.

cli/Stubs/service/service.stub traz um exemplo genérico com parâmetro $userId e comentários/chave user_id para registros pertencentes a um usuário. É um scaffold para novos Services, não uma exigência do framework. Se sua convenção for PT-BR, adapte o stub e as classes já geradas; preserve o nome da coluna no banco se o schema continuar igual. O stub de Controller usa $this->userId() em exemplo comentado; esse método é do Controller do framework e não deve ser renomeado isoladamente.

Bibliotecas e contratos externos

O composer.json lista PHP, vlucas/phpdotenv, phpmailer/phpmailer e PHPUnit; não há nesses pacotes uma exigência de classe User ou tabela users. A regra PSR-4 exige que namespace/caminho/classe sejam consistentes, não que estejam em inglês. Não altere código instalado em vendor/. Os contratos que realmente podem ser afetados são seu banco já implantado, sua API pública e os consumidores que você controla.

Algumas correspondências são apenas falso positivo de busca: DB_USERNAME é o login da conexão MySQL; MAIL_USERNAME é credencial SMTP; User-Agent é um header HTTP padronizado. Não são nomes da entidade do domínio. Comentários/exemplos genéricos em arquivos do framework também não alteram comportamento em execução.

O que não precisa ser alterado

• Não precisa mudar nada para usar o framework: User/users pode permanecer. A interface pode mostrar “Usuário”, “Nome”, “Senha” e “Perfil” enquanto os identificadores permanecem estáveis.
• Se a intenção for somente renomear a classe da aplicação, não é obrigatório mudar tabela, colunas, URLs, JSON, chaves de sessão ou nomes de middlewares.
• Não traduza DB_USERNAME, MAIL_USERNAME ou o header User-Agent; pertencem à configuração de conexão/protocolo.
• Não altere bibliotecas instaladas em vendor/ para trocar uma convenção do seu domínio.
• users_id não existe atualmente; não há referência a atualizar. Confirme usando pesquisa de código depois de suas próprias extensões.
• app/Models/RedefinicaoSenha.php e a migration database/migrations/0001_01_01_100001_create_redefinicoes_senha_table.php já usam PT-BR e não possuem FK de usuário nesta implementação.
• Não existe config/auth.php; a configuração do Model é a chamada Auth::setUserModel() em bootstrap.
• composer.json já usa PSR-4 genérico para App\; renomear uma classe corretamente não exige alterar o mapeamento. Após mudanças, confira o autoload otimizado.

O que não deve ser alterado

• Código em vendor/: não altere diretamente código de bibliotecas instaladas pelo Composer. As dependências atuais não exigem o nome de domínio User; mantenha o contrato de uma biblioteca externa se uma integração futura exigir determinado campo.
• Migrations já aplicadas: não as reescreva para esconder mudanças do banco. Preserve o histórico e crie migration nova com teste e rollback.
• Núcleo do Auth por conveniência: não renomeie isoladamente Auth::user(), chaves da sessão nem SQL de remember-me. Table/column rename exige manter uma alteração no framework e atualizar rotas, login, recuperação de cookie e logout.
• Contrato público sem coordenação: não troque /api/v1/users, data.user ou chaves JSON de uma API já consumida sem atualizar/versionar frontend, aplicativos, integrações e documentação.
• Convenções de protocolo: não traduza User-Agent, Authorization: Bearer ou nomes de variáveis de terceiros apenas por conterem a palavra “user”.

“Deve permanecer” significa preservar enquanto o contrato atual for necessário — não significa que um fork ou uma API versionada jamais possa mudar. A mudança deliberada precisa ser coordenada e compatível com os dados e consumidores.

Como adaptar sua aplicação para PT-BR

1. Defina o alcance. Escolha entre traduzir apenas textos visíveis, renomear classes PHP, renomear colunas/tabela ou alterar contratos HTTP. A alternativa de menor risco é localizar a UI e renomear somente classes app-owned.
2. Mapeie o ponto de partida. Revise app/Models/User.php, app/Repositories/UserRepository.php, AuthService e as rotas. Leia Models e estrutura do projeto.
3. Se renomear a classe, mova o arquivo e preserve seu contrato. Crie Usuario.php, mantenha a tabela explicitamente escolhida e porte métodos/campos usados pelo Auth. Atualize imports e tipos; execute composer dump-autoload.
4. Configure o Auth antes do primeiro uso. Adicione Auth::setUserModel(Usuario::class) no bootstrap antes da recuperação de cookie. Atualize também as construções diretas de Model em Controllers Web/API; a configuração não as substitui.
5. Atualize relacionamentos e camadas. Ajuste a FK/coluna quando necessário e atualize Repository, Service, Controllers Web/API, Resource, middleware e seeder. Use a tabela de arquivos desta página e pesquise ocorrências restantes.
6. Revise a migration e o vínculo. Inspecione 0001_01_01_100000_create_users_table.php, 0001_01_01_100002_add_remember_token_expires_at_to_users_table.php e 0001_01_01_100003_create_api_tokens_table.php; não há relação ORM genérica, mas existe a FK api_tokens.user_id. Se o projeto ainda não foi migrado, pode ajustar a migration original. Em produção, preserve o histórico, crie nova migration e adapte o SQL direto do Auth; consulte Migrations e Schema e Database e PDO.
7. Alinhe Requests e Views. Altere em conjunto nomes dos campos, regras, sanitização, mensagens, formulários e acessos aos atributos. Veja Requests e FormRequest e Validação.
8. Preserve ou versione o contrato da API. Mude URL ou JSON somente depois de atualizar clientes e a documentação externa. Consulte API HTTP e endpoints próprios e Roteamento.
9. Revise geradores. Se os projetos novos também devem seguir PT-BR, ajuste o stub pertinente em cli/Stubs/ e regenere/autocorrija o código. Mudanças no stub não alteram arquivos já gerados.
10. Valide fluxos completos. Faça lint PHP e testes próprios: cadastro, login/logout, recuperação/reset, remember-me, sessão, token Bearer, /auth/me, lista/detalhe, Views, uploads com arquivos antigos e rollback em cópia do banco. Teste clientes afetados pela API e integrações.

Exemplo prático: classe em português, contratos preservados

Cenário: você quer escrever a aplicação com o nome Usuario, mas não precisa alterar dados já armazenados nem quebrar o front-end/API. O objetivo é renomear a classe PHP e continuar usando a tabela e os campos que o Auth existente entende.

1. Crie/adapte app/Models/Usuario.php a partir de User.php, mantendo $table = 'users', campos usados pelo projeto e métodos de autenticação.
2. Atualize UserRepository para configurar Usuario::class (ou renomeie o Repository e seus consumidores).
3. Configure Auth::setUserModel(Usuario::class) no bootstrap antes do primeiro uso.
4. Atualize referências diretas em AuthController, AuthApiController, Repositories e Resources. Mantenha /api/v1/users e o JSON atual se eles já forem consumidos.

// Classe da aplicação e sua tabela são decisões independentes.
class Usuario extends Model
{
    protected string $table = 'users';
    // ...portar fillable, hidden e métodos reais de autenticação
}

// bootstrap/app.php: depois do autoload e antes de Auth::recoverFromCookie().
\Framework\Auth\Auth::setUserModel(\App\Models\Usuario::class);

Resultado esperado: o código da aplicação pode referir-se à classe Usuario, enquanto o schema users, os campos name/email/password/role/active, a sessão user_id e os contratos JSON/URLs permanecem compatíveis. Isso só funciona depois de atualizar todo uso direto da classe antiga; setUserModel() não reescreve imports nem instâncias explícitas.

Checklist de mudança

• ☐ Escolhi exatamente quais camadas traduzir: interface, classe, banco, API ou todas.
• ☐ Renomeei arquivo/classe com namespace PSR-4 consistente e declarei $table.
• ☐ Preservei/atualizei authenticate(), findById(), propriedades id/email/role/active e campos ocultos.
• ☐ Atualizei Repository, Service, Controllers, Requests, Resources e Middleware que realmente usam o Model/campos.
• ☐ Decidi conscientemente sobre tabela users, colunas, migration aplicada, índices e FK api_tokens.user_id.
• ☐ Se tabela/colunas mudaram, atualizei o SQL de remember-me/logout no Auth e validei uma migration reversível em cópia.
• ☐ Alinhei formulários, labels, atributos name, validações, sanitização e mensagens.
• ☐ Preservei as URLs/JSON públicos ou atualizei e versionei os consumidores, testes e documentação.
• ☐ Revisei UserSeeder, stubs futuros, aliases e comandos de execução de seed.
• ☐ Não alterei vendor/ nem nomes técnicos sem identificar seus consumidores.
• ☐ Rodei lint e testes de regressão próprios para Web, sessão/remember-me, API Bearer, recursos e migration.

Para uma alteração incremental, localize nomes residuais e avalie cada ocorrência no contexto; uma ocorrência restante pode ser intencional, como uma chave JSON ainda pública ou um nome de tabela preservado:

rg -n -i 'User|users|user_id|user_role' app framework bootstrap config database routes cli resources

Consulte também Autenticação, Resources, Controllers, Middleware, Sessões e CSRF, Migrations e Schema, Services e Repositories. A nomenclatura em português é uma escolha da aplicação; compatibilidade, dados e contratos devem orientar o alcance da mudança.