palladium
Who is that "index" and where to find it
(trabalho em andamento: documentos para 2.0)
Biblioteca para tratamento da identificação do usuário.
O objetivo desta biblioteca é localizar a conta do usuário (para ser mais preciso - seu ID exclusivo) para uma determinada prova de identidade e gerenciar vários tipos de identidades. É composto por 4 serviços distintos: Identificação, Registo, Busca e Recuperação.
Você pode adicionar a biblioteca ao seu projeto usando o compositor com o seguinte comando:
composer require teresko/ palladiumPara usar este pacote, é necessário PHP versão 7.0+ e PDO.
Você também precisará criar uma tabela, onde armazenar as identidades . O esquema de exemplo está disponível aqui. Atualmente contém apenas definição de tabela para MySQL/MariaDB, mas a biblioteca pode ser usada com qualquer RDBMS, que possua driver PDO.
palladium contém 4 serviços: Registration , Identification , Search e Recovery . Cada um desses serviços possui duas dependências obrigatórias:
palladium ContractCanPersistIdenity )PsrLogLoggerInterface )Isso lhe dá a opção de substituir o repositório padrão, se desejar alterar ou substituir partes da camada de abstração de persistência. Quanto ao logger - a abordagem recomendada é usar o Monolog, mas funcionaria com qualquer sistema de registro compatível.
O repositório padrão também vem com funcionalidade para adicionar tipos de identidade personalizados e mapeadores de dados, que são usados para seus tipos de identidade ou para os tipos de identidade integrados. Para detalhes de uso, consulte a seção %TODO%.
No construtor do serviço Identification existe um terceiro e quarto parâmetros opcionais:
No construtor do serviço Registration existe um terceiro parâmetro opcional:
Conforme observado acima, todos os 4 serviços esperam um repositório como uma dependência do construtor. Se você não estiver substituindo o repositório empacotado pela sua versão personalizada, você precisará inicializar palladium RepositoryIdentity e passá-lo para os serviços.
O repositório incluído em si tem uma única dependência: instance, que implementa palladium ContractCanCreateMapper . Este contrato (interface) é implementado por palladium ComponentMapperFactory . E esta fábrica possui duas dependências: a instância PDO e o nome da tabela, onde serão armazenadas as identidades .
<?php
$ factory = new palladium Component MapperFactory ( new PDO (... $ config ), $ tableName );
$ repository = new palladium Repository Identity ( $ factory ); Em todos os outros exemplos de código, onde você vê a variável $repository usada, você pode assumir que ela foi inicializada usando este exemplo de código.
Para usuários do componente DependencyInjection do Symfony (versão: 3.4+), há um arquivo de configuração de exemplo: %TODO%
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Se a operação for concluída com sucesso, a variável $identity conterá uma instância de StandardIdentity não verificada. Para completar a verificação, você terá que usar o token que a identidade contém. No exemplo dado, este token pode ser avaliado usando $instance->getToken() .
O método createStandardIdentity() pode lançar a exceção IdentityConflict , se o e-mail já tiver sido usado para outra identidade.
O método createStandardIdentity() possui um terceiro parâmetro opcional, que define a vida útil do token de verificação de e-mail em segundos. Quando aplicado, o exemplo anterior fica assim:
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' , 3600 );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Isso tornará o token de verificação utilizável por 1 hora após o registro da identidade do usuário. Depois que esse tempo passar, você não conseguirá encontrar essa identidade usando findStandardIdentityByToken() no serviço Search .
IMPORTANTE : o método
createStandardIdentity()não valida o email dos usuários ou qualquer outro tipo de identificador. Ele apenas verifica sua singularidade. A validação de e-mails, números de telefone, apelidos e outros identificadores está além do escopo desta biblioteca.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByToken ( $ token , palladium Entity Identity:: ACTION_VERIFY );
$ registration -> verifyStandardIdentity ( $ identity ); O valor $token é usado para localizar o EmailIdentity correspondente, que então é verificado. Se a identidade não for encontrada, findStandardIdentityByToken() lançará a exceção IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ cookie = $ identification -> loginWithPassword ( $ identity , $ password ); Se não houver identidade correspondente com determinado identificador (como endereço de e-mail) encontrada, o método findStandardIdentityByIdentifier() lançará a exceção IdentityNotFound .
Caso a senha não corresponda, o método loginWithPassword() lançará a exceção PasswordMismatch .
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId ); Isto criará uma nova instância de NonceIdentity . Para usá-lo para login, você precisará de valores em NonceIdentity::getIdentifier() e NonceIdentity::getKey() , onde o identificador será usado para localizar a identidade nonce e a chave será usada para verificar.
O método createNonceIdentity() era um segundo parâmetro opcional, que define a vida útil dessa identidade de uso único em segundos. Quando aplicado, o exemplo anterior fica assim:
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId , 600 ); Isso tornará a identidade de uso único utilizável por 10 minutos após sua criação. Depois que o tempo permitido tiver passado, passar essa identidade no método useNonceIdentity() de Identification resultará no lançamento da exceção IdentityExpired .
<?php
$ identity = $ this -> search -> findNonceIdentityByIdentifier ( $ identifier );
$ cookie = $ this -> identification -> useNonceIdentity ( $ identity , $ key ); Se não houver identidade correspondente com determinado identificador (endereço de e-mail, apelido, etc.) encontrada, o método findNonceIdentityByIdentifier() lançará a exceção IdentityNotFound .
Caso a senha não corresponda, o método useNonceIdentity() lançará a exceção KeyMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ cookie = $ identification -> loginWithCookie ( $ identity , $ key ); Se o cookie não for encontrado usando findCookieIdentity() uma exceção padrão IdentityNotFound será lançada. A possível causa seria que o cookie não estivesse mais ativo (por exemplo, usuário desconectado) ou o cookie não existisse.
Caso o cookie seja muito antigo, loginWithCookie() produzirá a exceção IdentityExpired .
Mas o método loginWithCookie() também pode produzir uma exceção CompromisedCookie . Ver uma exceção para isso pode indicar que o cookie foi roubado ou que o usuário nunca recebeu um novo valor de cookie.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> blockIdentity ( $ identity );Esta é a forma recomendada para lidar com cookies suspeitos, que podem ou não ser roubados. Isto não se destina a desconectar usuários .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> logout ( $ identity , $ key );Esta operação marca o cookie como “descartado”. A lista de exceções que podem ser produzidas corresponde às descritas na seção login usando cookies.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity ); Se não for encontrada nenhuma identidade correspondente com o endereço de e-mail fornecido, o método findStandardIdentityByIdentifier() lançará a exceção IdentityNotFound .
Quando markForReset() é chamado, ele deve ser fornecido com uma instância de StandardIdentity , que já foi verificada (caso contrário, pode vazar informações privadas do usuário de seu aplicativo). Se não for esse o caso, o método lançará a exceção IdentityNotVerified .
O método markForReset() era um segundo parâmetro opcional, que define a vida útil do token de redefinição de senha em segundos. Quando aplicado, o exemplo anterior fica assim:
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity , 7200 ); Isso tornará o token de redefinição de senha utilizável por duas horas após a identidade desse usuário ter sido marcada para redefinição. Quando o tempo permitido expirar, você não conseguirá encontrar essa identidade usando findEmailIdentityByToken() no serviço Search .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findEmailIdentityByToken ( $ token , palladium Entity Identity:: ACTION_RESET );
$ recovery -> resetIdentityPassword ( $ identity , ' foobar ' ); Se não houver identidade correspondente com determinado token encontrado, o método findEmailIdentityByToken() lançará a exceção IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ identification -> changePassword ( $ identity , $ oldPassword , $ newPassword ); Se não houver identidade correspondente com determinado endereço de e-mail (ou qualquer outro tipo de identificador) encontrada, o método findStandardIdentityByIdentifier() lançará a exceção IdentityNotFound .
Caso a senha não corresponda, o método changePassword() lançará a exceção PasswordMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ factory , $ logger );
$ list = $ search -> findIdentitiesByParentId ( $ identity -> getId ());
$ identification -> discardIdentityCollection ( $ list ); O valor de retorno de findIdentitiesByParentId() retornará IdentityCollection , que pode estar vazio.
Conforme mencionado anteriormente, os serviços nesta biblioteca esperam um criador de logs compatível com PSR-3 como dependência. Ele será utilizado para registrar três níveis de eventos:
LogLevel::INFOEste nível de log é usado para rastrear operações comuns que o usuário realizaria ao usar seu aplicativo da maneira pretendida:
LogLevel::NOTICELogs com este nível serão registrados, se o usuário tentar uma operação malsucedida, o que não deveria acontecer em cenários de uso corretos:
LogLevel::WARNINGUsado apenas para registrar casos, quando o usuário tentou usar um cookie comprometido.
Esta biblioteca se concentra em uma tarefa específica. Não inclui nenhuma das seguintes funcionalidades:
Se você acha que essa biblioteca de autenticação requer uma das partes listadas acima, então esta não é a biblioteca que você está procurando.
