Uma biblioteca php simples que contém asserções e métodos de proteção para validação de entrada (não filtragem!) Em modelo de negócios, bibliotecas e código de baixo nível de aplicativo. A biblioteca pode ser usada para implementar pré/pós-condições nos dados de entrada.
A ideia é reduzir a quantidade de código para implementar asserções em seu modelo e também simplificar os caminhos do código para implementar asserções. Quando as asserções falham, uma exceção é lançada, eliminando a necessidade de cláusulas if em seu código.
A biblioteca não está usando Symfony ou Zend Validators por um motivo: as verificações devem ser códigos de baixo nível, rápidos e não orientados a objetos para serem usados em todos os lugares necessários. O uso de qualquer uma das duas bibliotecas requer a instanciação de vários objetos, usando um componente de localidade, traduções, o que você quiser. É muito inchaço.
Usando o compositor:
composer require beberlei/assert
<?php
use Assert Assertion ;
function duplicateFile ( $ file , $ times )
{
Assertion :: file ( $ file );
Assertion :: digit ( $ times );
for ( $ i = 0 ; $ i < $ times ; $ i ++) {
copy ( $ file , $ file . $ i );
}
}
Uso em tempo real com o Azure Blob Storage:
<?php
public function putBlob ( $ containerName = '' , $ blobName = '' , $ localFileName = '' , $ metadata = array (), $ leaseId = null , $ additionalHeaders = array ())
{
Assertion :: notEmpty ( $ containerName , ' Container name is not specified ' );
self :: assertValidContainerName ( $ containerName );
Assertion :: notEmpty ( $ blobName , ' Blob name is not specified. ' );
Assertion :: notEmpty ( $ localFileName , ' Local file name is not specified. ' );
Assertion :: file ( $ localFileName , ' Local file name is not specified. ' );
self :: assertValidRootContainerBlobName ( $ containerName , $ blobName );
// Check file size
if ( filesize ( $ localFileName ) >= self :: MAX_BLOB_SIZE ) {
return $ this -> putLargeBlob ( $ containerName , $ blobName , $ localFileName , $ metadata , $ leaseId , $ additionalHeaders );
}
// Put the data to Windows Azure Storage
return $ this -> putBlobData ( $ containerName , $ blobName , file_get_contents ( $ localFileName ), $ metadata , $ leaseId , $ additionalHeaders );
}
Um método auxiliar ( Assertion::nullOr*
) é fornecido para verificar se um valor é nulo OU válido para a afirmação:
<?php
Assertion :: nullOrMax ( null , 42 ); // success
Assertion :: nullOrMax ( 1 , 42 ); // success
Assertion :: nullOrMax ( 1337 , 42 ); // exception
O método Assertion::all*
verifica se todos os valores fornecidos são válidos para a asserção. Isso lançará uma exceção da afirmação que não é válida para um dos valores:
<?php
Assertion :: allIsInstanceOf ( array ( new stdClass, new stdClass), ' stdClass ' ); // success
Assertion :: allIsInstanceOf ( array ( new stdClass, new stdClass), ' PDO ' ); // exception
Usar a API estática em valores é muito detalhado ao verificar valores em relação a múltiplas asserções. Começando com 2.6.7 de Assert, a classe Assert
fornece uma API fluente muito mais agradável para asserções, começando com Assert::that($value)
e depois recebendo as asserções que você deseja chamar na interface fluente. Você só precisa especificar o $value
uma vez.
<?php
Assert :: that ( $ value )-> notEmpty ()-> integer ();
Assert :: that ( $ value )-> nullOr ()-> string ()-> startsWith ( " Foo " );
Assert :: that ( $ values )-> all ()-> float ();
Existem também duas funções de atalho Assert::thatNullOr()
e Assert::thatAll()
habilitando o auxiliar "nullOr" ou "all" respectivamente.
Existem muitos casos no desenvolvimento web, principalmente quando envolve formulários, você deseja coletar vários erros ao invés de abortar diretamente no primeiro erro. É para isso que servem as afirmações preguiçosas. Sua API funciona exatamente como a API fluente Assert::that()
, mas em vez de lançar uma exceção diretamente, eles coletam todos os erros e só acionam a exceção quando o método verifyNow()
é chamado no objeto AssertSoftAssertion
.
<?php
Assert :: lazy ()
-> that ( 10 , ' foo ' )-> string ()
-> that ( null , ' bar ' )-> notEmpty ()
-> that ( ' string ' , ' baz ' )-> isArray ()
-> verifyNow ();
O método that($value, $propertyPath)
requer um caminho de propriedade (nome), para que você saiba diferenciar os erros posteriormente.
Em caso de falha, verifyNow()
lançará uma exceção Assert\LazyAssertionException
com uma mensagem combinada:
The following 3 assertions failed:
1) foo: Value "10" expected to be string, type integer given.
2) bar: Value "<NULL>" is empty, but non empty value was expected.
3) baz: Value "string" is not an array.
Você também pode recuperar todos os AssertionFailedException
s chamando getErrorExceptions()
. Isto pode ser útil, por exemplo, para criar uma resposta de falha para o usuário.
Para aqueles que procuram capturar vários erros em um único valor ao usar uma cadeia de asserção lenta, você pode seguir sua chamada com that
para executar todas as asserções em relação ao valor e capturar todas as mensagens de tryAll
de asserção com falha resultantes. Aqui está um exemplo:
Assert :: lazy ()
-> that ( 10 , ' foo ' )-> tryAll ()-> integer ()-> between ( 5 , 15 )
-> that ( null , ' foo ' )-> tryAll ()-> notEmpty ()-> string ()
-> verifyNow ();
A descrição acima mostra como usar essa funcionalidade para ajustar o comportamento de relatar falhas, mas para tornar a detecção de todas as falhas ainda mais fácil, você também pode chamar tryAll
antes de fazer qualquer afirmação como abaixo. Isso ajuda a reduzir chamadas de métodos e tem o mesmo comportamento acima.
Assert :: lazy ()-> tryAll ()
-> that ( 10 , ' foo ' )-> integer ()-> between ( 5 , 15 )
-> that ( null , ' foo ' )-> notEmpty ()-> string ()
-> verifyNow ();
As seguintes funções existem como aliases para construtores estáticos Assert
:
Assertthat()
AssertthatAll()
AssertthatNullOr()
Assertlazy()
Usar os construtores funcionais ou estáticos é uma preferência inteiramente pessoal.
Nota: Os construtores funcionais não funcionarão com uma extensão Assertion
. No entanto, é trivial recriar essas funções de uma forma que aponte para a classe estendida.
<?php
use Assert Assertion ;
Assertion :: alnum (mixed $ value );
Assertion :: base64 (string $ value );
Assertion :: between (mixed $ value , mixed $ lowerLimit , mixed $ upperLimit );
Assertion :: betweenExclusive (mixed $ value , mixed $ lowerLimit , mixed $ upperLimit );
Assertion :: betweenLength (mixed $ value , int $ minLength , int $ maxLength );
Assertion :: boolean (mixed $ value );
Assertion :: choice (mixed $ value , array $ choices );
Assertion :: choicesNotEmpty (array $ values , array $ choices );
Assertion :: classExists (mixed $ value );
Assertion :: contains (mixed $ string , string $ needle );
Assertion ::count(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: date (string $ value , string $ format );
Assertion :: defined (mixed $ constant );
Assertion :: digit (mixed $ value );
Assertion :: directory (string $ value );
Assertion :: e164 (string $ value );
Assertion :: email (mixed $ value );
Assertion :: endsWith (mixed $ string , string $ needle );
Assertion :: eq (mixed $ value , mixed $ value2 );
Assertion :: eqArraySubset (mixed $ value , mixed $ value2 );
Assertion :: extensionLoaded (mixed $ value );
Assertion :: extensionVersion (string $ extension , string $ operator , mixed $ version );
Assertion :: false (mixed $ value );
Assertion :: file (string $ value );
Assertion :: float (mixed $ value );
Assertion :: greaterOrEqualThan (mixed $ value , mixed $ limit );
Assertion :: greaterThan (mixed $ value , mixed $ limit );
Assertion :: implementsInterface (mixed $ class , string $ interfaceName );
Assertion :: inArray (mixed $ value , array $ choices );
Assertion :: integer (mixed $ value );
Assertion :: integerish (mixed $ value );
Assertion :: interfaceExists (mixed $ value );
Assertion :: ip (string $ value , int $ flag = null );
Assertion :: ipv4 (string $ value , int $ flag = null );
Assertion :: ipv6 (string $ value , int $ flag = null );
Assertion :: isArray (mixed $ value );
Assertion :: isArrayAccessible (mixed $ value );
Assertion :: isCallable (mixed $ value );
Assertion ::isCountable(array| Countable | ResourceBundle | SimpleXMLElement $ value );
Assertion :: isInstanceOf (mixed $ value , string $ className );
Assertion :: isJsonString (mixed $ value );
Assertion :: isObject (mixed $ value );
Assertion :: isResource (mixed $ value );
Assertion :: isTraversable (mixed $ value );
Assertion :: keyExists (mixed $ value , string|int $ key );
Assertion :: keyIsset (mixed $ value , string|int $ key );
Assertion :: keyNotExists (mixed $ value , string|int $ key );
Assertion :: length (mixed $ value , int $ length );
Assertion :: lessOrEqualThan (mixed $ value , mixed $ limit );
Assertion :: lessThan (mixed $ value , mixed $ limit );
Assertion :: max (mixed $ value , mixed $ maxValue );
Assertion ::maxCount(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: maxLength (mixed $ value , int $ maxLength );
Assertion :: methodExists (string $ value , mixed $ object );
Assertion :: min (mixed $ value , mixed $ minValue );
Assertion ::minCount(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: minLength (mixed $ value , int $ minLength );
Assertion :: noContent (mixed $ value );
Assertion :: notBlank (mixed $ value );
Assertion :: notContains (mixed $ string , string $ needle );
Assertion :: notEmpty (mixed $ value );
Assertion :: notEmptyKey (mixed $ value , string|int $ key );
Assertion :: notEq (mixed $ value1 , mixed $ value2 );
Assertion :: notInArray (mixed $ value , array $ choices );
Assertion :: notIsInstanceOf (mixed $ value , string $ className );
Assertion :: notNull (mixed $ value );
Assertion :: notRegex (mixed $ value , string $ pattern );
Assertion :: notSame (mixed $ value1 , mixed $ value2 );
Assertion :: null (mixed $ value );
Assertion :: numeric (mixed $ value );
Assertion :: objectOrClass (mixed $ value );
Assertion :: phpVersion (string $ operator , mixed $ version );
Assertion :: propertiesExist (mixed $ value , array $ properties );
Assertion :: propertyExists (mixed $ value , string $ property );
Assertion :: range (mixed $ value , mixed $ minValue , mixed $ maxValue );
Assertion :: readable (string $ value );
Assertion :: regex (mixed $ value , string $ pattern );
Assertion :: same (mixed $ value , mixed $ value2 );
Assertion :: satisfy (mixed $ value , callable $ callback );
Assertion :: scalar (mixed $ value );
Assertion :: startsWith (mixed $ string , string $ needle );
Assertion :: string (mixed $ value );
Assertion :: subclassOf (mixed $ value , string $ className );
Assertion :: true (mixed $ value );
Assertion :: uniqueValues (array $ values );
Assertion :: url (mixed $ value );
Assertion :: uuid (string $ value );
Assertion :: version (string $ version1 , string $ operator , string $ version2 );
Assertion :: writeable (string $ value );
Lembre-se: Quando um parâmetro de configuração é necessário, ele sempre é passado DEPOIS do valor. O valor é sempre o primeiro parâmetro.
Se alguma das asserções falhar, uma AssertAssertionFailedException
será lançada. Você pode passar um argumento chamado $message
para qualquer asserção para controlar a mensagem de exceção. Cada exceção contém uma mensagem padrão e um código de mensagem exclusivo por padrão.
<?php
use Assert Assertion ;
use Assert AssertionFailedException ;
try {
Assertion :: integer ( $ value , " The pressure of gas is measured in integers. " );
} catch ( AssertionFailedException $ e ) {
// error handling
$ e -> getValue (); // the value that caused the failure
$ e -> getConstraints (); // the additional constraints of the assertion.
}
AssertAssertionFailedException
é apenas uma interface e a implementação padrão é AssertInvalidArgumentException
que estende o SPL InvalidArgumentException
. Você pode alterar a exceção usada em um nível baseado em pacote.
Você pode passar um retorno de chamada como parâmetro de mensagem, permitindo construir sua própria mensagem somente se uma asserção falhar, em vez de sempre que você executar o teste.
O retorno de chamada será fornecido com uma matriz de parâmetros que servem para a asserção.
Como algumas asserções chamam outras asserções, seu retorno de chamada precisará exemplificar a matriz para determinar qual asserção falhou.
A matriz conterá uma chave chamada ::assertion
que indica qual afirmação falhou.
O retorno de chamada deve retornar a string que será usada como mensagem de exceção.
Para proteger sua biblioteca de possíveis bugs, interpretações incorretas ou quebras de BC dentro do Assert, você deve introduzir uma subclasse de asserção baseada em biblioteca/projeto, onde você também pode substituir a exceção lançada.
Além disso, você pode substituir o método AssertAssertion::stringify()
para fornecer suas próprias interpretações dos tipos durante o tratamento de erros.
<?php
namespace MyProject ;
use Assert Assertion as BaseAssertion ;
class Assertion extends BaseAssertion
{
protected static $ exceptionClass = ' MyProjectAssertionFailedException ' ;
}
A partir da V2.9.2, as Asserções Preguiçosas agora têm acesso a quaisquer asserções adicionais presentes em suas próprias classes de asserção.
Consulte CONTRIBUINDO para obter mais detalhes.