klein.php
Version 2.1.2 - PHP 7 `Throwable` exception compatibility
klein.php é um roteador rápido e flexível para PHP 5.3+
php composer.phar require klein/kleinrequire 'vendor/autoload.php'; Hello World - Exemplo obrigatório de hello world
<?php
require_once __DIR__ . ' /vendor/autoload.php ' ;
$ klein = new Klein Klein ();
$ klein -> respond ( ' GET ' , ' /hello-world ' , function () {
return ' Hello World! ' ;
});
$ klein -> dispatch ();Exemplo 1 – Responder a todas as solicitações
$ klein -> respond ( function () {
return ' All the things ' ;
});Exemplo 2 – Parâmetros nomeados
$ klein -> respond ( ' /[:name] ' , function ( $ request ) {
return ' Hello ' . $ request -> name ;
});Exemplo 3 – Tão RESTful
$ klein -> respond ( ' GET ' , ' /posts ' , $ callback );
$ klein -> respond ( ' POST ' , ' /posts ' , $ callback );
$ klein -> respond ( ' PUT ' , ' /posts/[i:id] ' , $ callback );
$ klein -> respond ( ' DELETE ' , ' /posts/[i:id] ' , $ callback );
$ klein -> respond ( ' OPTIONS ' , null , $ callback );
// To match multiple request methods:
$ klein -> respond ( array ( ' POST ' , ' GET ' ), $ route , $ callback );
// Or you might want to handle the requests in the same place
$ klein -> respond ( ' /posts/[create|edit:action]?/[i:id]? ' , function ( $ request , $ response ) {
switch ( $ request -> action ) {
//
}
});Exemplo 4 – Envio de objetos/arquivos
$ klein ->respond( function ( $ request , $ response , $ service ) {
$ service -> xml = function ( $ object ) {
// Custom xml output function
}
$ service -> csv = function ( $ object ) {
// Custom csv output function
}
});
$ klein -> respond ( ' /report.[xml|csv|json:format]? ' , function ( $ request , $ response , $ service ) {
// Get the format or fallback to JSON as the default
$ send = $ request -> param ( ' format ' , ' json ' );
$ response -> $ send ( $ report );
});
$ klein -> respond ( ' /report/latest ' , function ( $ request , $ response , $ service ) {
$ response -> file ( ' /tmp/cached_report.zip ' );
});Exemplo 5 – Todos juntos
$ klein -> respond ( function ( $ request , $ response , $ service , $ app ) use ( $ klein ) {
// Handle exceptions => flash the message and redirect to the referrer
$ klein -> onError ( function ( $ klein , $ err_msg ) {
$ klein -> service ()-> flash ( $ err_msg );
$ klein -> service ()-> back ();
});
// The fourth parameter can be used to share scope and global objects
$ app -> db = new PDO (...);
// $app also can store lazy services, e.g. if you don't want to
// instantiate a database connection on every response
$ app -> register ( ' db ' , function () {
return new PDO (...);
});
});
$ klein -> respond ( ' POST ' , ' /users/[i:id]/edit ' , function ( $ request , $ response , $ service , $ app ) {
// Quickly validate input parameters
$ service -> validateParam ( ' username ' , ' Please enter a valid username ' )-> isLen ( 5 , 64 )-> isChars ( ' a-zA-Z0-9- ' );
$ service -> validateParam ( ' password ' )-> notNull ();
$ app -> db -> query (...); // etc.
// Add view properties and helper methods
$ service -> title = ' foo ' ;
$ service -> escape = function ( $ str ) {
return htmlentities ( $ str ); // Assign view helpers
};
$ service -> render ( ' myview.phtml ' );
});
// myview.phtml:
<title> <?php echo $ this -> escape ( $ this -> title ) ?> </title> $ klein -> with ( ' /users ' , function () use ( $ klein ) {
$ klein -> respond ( ' GET ' , ' /? ' , function ( $ request , $ response ) {
// Show all users
});
$ klein -> respond ( ' GET ' , ' /[:id] ' , function ( $ request , $ response ) {
// Show a single user
});
});
foreach ( array ( ' projects ' , ' posts ' ) as $ controller ) {
// Include all routes defined in a file under a given namespace
$ klein -> with ( " / $ controller " , " controllers/ $ controller .php " );
} Os arquivos incluídos são executados no escopo do Klein ( $klein ) para que todos os métodos/propriedades do Klein possam ser acessados com $this
Arquivo de exemplo para: "controllers/projects.php"
// Routes to "/projects/?"
$ this -> respond ( ' GET ' , ' /? ' , function ( $ request , $ response ) {
// Show all projects
});Os serviços podem ser armazenados preguiçosamente , o que significa que só são instanciados na primeira utilização.
<?php
$ klein -> respond ( function ( $ request , $ response , $ service , $ app ) {
$ app -> register ( ' lazyDb ' , function () {
$ db = new stdClass ();
$ db -> name = ' foo ' ;
return $ db ;
});
});
//Later
$ klein -> respond ( ' GET ' , ' /posts ' , function ( $ request , $ response , $ service , $ app ) {
// $db is initialised on first request
// all subsequent calls will use the same instance
return $ app -> lazyDb -> name ;
}); Para adicionar um validador personalizado, use addValidator($method, $callback)
$ service -> addValidator ( ' hex ' , function ( $ str ) {
return preg_match ( ' /^[0-9a-f]++$/i ' , $ str );
}); Você pode validar parâmetros usando is<$method>() ou not<$method>() , por exemplo
$ service -> validateParam ( ' key ' )-> isHex ();Ou você pode validar qualquer string usando o mesmo fluxo.
$ service -> validate ( $ username )-> isLen ( 4 , 16 );Os métodos de validação podem ser encadeados e uma mensagem de exceção personalizada pode ser especificada para se/quando a validação falhar
$ service -> validateParam ( ' key ' , ' The key was invalid ' )-> isHex ()-> isLen ( 32 );[ tipo_correspondência : nome_param ]
Alguns exemplos
* // Match all request URIs
[i] // Match an integer
[i:id] // Match an integer as 'id'
[a:action] // Match alphanumeric characters as 'action'
[h:key] // Match hexadecimal characters as 'key'
[:action] // Match anything up to the next / or end of the URI as 'action'
[create|edit:action] // Match either 'create' or 'edit' as 'action'
[*] // Catch all (lazy)
[*:trailing] // Catch all as 'trailing' (lazy)
[**:trailing] // Catch all (possessive - will match the rest of the URI)
.[:format]? // Match an optional parameter 'format' - a / or . before the block is also optional
Alguns exemplos mais complicados
/posts/[*:title][i:id] // Matches "/posts/this-is-a-title-123"
/output.[xml|json:format]? // Matches "/output", "output.xml", "output.json"
/[:controller]?/[:action]? // Matches the typical /controller/action format
Observação - todas as rotas que correspondem ao URI da solicitação são chamadas - isso permite incorporar lógica condicional complexa, como autenticação de usuário ou layouts de visualização. por exemplo, como exemplo básico, o código a seguir envolverá outras rotas com um cabeçalho e rodapé
$ klein -> respond ( ' * ' , function ( $ request , $ response , $ service ) { $ service -> render ( ' header.phtml ' ); });
//other routes
$ klein -> respond ( ' * ' , function ( $ request , $ response , $ service ) { $ service -> render ( ' footer.phtml ' ); }); As rotas correspondem automaticamente a todo o URI da solicitação. Se você precisar corresponder apenas uma parte do URI da solicitação ou usar uma expressão regular personalizada, use o operador @ . Se você precisar negar uma rota, use o comando ! operador
// Match all requests that end with '.json' or '.csv'
$ klein ->respond( ' @.(json|csv)$ ' , ...
// Match all requests that _don't_ start with /admin
$ klein ->respond( ' !@^/admin/ ' , ... Você pode enviar propriedades ou auxiliares para a visualização atribuindo-os ao objeto $service ou usando o segundo argumento de $service->render()
$ service -> escape = function ( $ str ) {
return htmlentities ( $ str );
};
$ service -> render ( ' myview.phtml ' , array ( ' title ' => ' My View ' ));
// Or just: $service->title = 'My View';minhavisualização.phtml
< title > < ?php echo $this- > escape($this- > title) ? > </ title > As visualizações são compiladas e executadas no escopo de $service para que todos os métodos de serviço possam ser acessados com $this
$ this -> render ( ' partial.html ' ) // Render partials
$ this -> sharedData ()-> get ( ' myvar ' ) // Access stored service variables
echo $ this -> query ( array ( ' page ' => 2 )) // Modify the current query string Abaixo está uma lista dos métodos públicos nas classes comuns que você provavelmente usará. Para uma fonte mais formal de documentação de classe/método, consulte a documentação gerada pelo PHPdoc.
$ request ->
id ( $ hash = true ) // Get a unique ID for the request
paramsGet() // Return the GET parameter collection
paramsPost() // Return the POST parameter collection
paramsNamed() // Return the named parameter collection
cookies() // Return the cookies collection
server() // Return the server collection
headers() // Return the headers collection
files() // Return the files collection
body() // Get the request body
params() // Return all parameters
params ( $ mask = null ) // Return all parameters that match the mask array - extract() friendly
param ( $ key , $ default = null ) // Get a request parameter (get, post, named)
isSecure() // Was the request sent via HTTPS?
ip() // Get the request IP
userAgent() // Get the request user agent
uri() // Get the request URI
pathname() // Get the request pathname
method() // Get the request method
method ( $ method ) // Check if the request method is $method, i.e. method('post') => true
query ( $ key , $ value = null ) // Get, add to, or modify the current query string
<param> // Get / Set (if assigned a value) a request parameter
$ response ->
protocolVersion ( $ protocol_version = null ) // Get the protocol version, or set it to the passed value
body ( $ body = null ) // Get the response body's content, or set it to the passed value
status() // Get the response's status object
headers() // Return the headers collection
cookies() // Return the cookies collection
code ( $ code = null ) // Return the HTTP response code, or set it to the passed value
prepend ( $ content ) // Prepend a string to the response body
append ( $ content ) // Append a string to the response body
isLocked() // Check if the response is locked
requireUnlocked() // Require that a response is unlocked
lock() // Lock the response from further modification
unlock() // Unlock the response
sendHeaders ( $ override = false ) // Send the HTTP response headers
sendCookies ( $ override = false ) // Send the HTTP response cookies
sendBody() // Send the response body's content
send() // Send the response and lock it
isSent() // Check if the response has been sent
chunk ( $ str = null ) // Enable response chunking (see the wiki)
header ( $ key , $ value = null ) // Set a response header
cookie ( $ key , $ value = null , $ expiry = null ) // Set a cookie
cookie ( $ key , null ) // Remove a cookie
noCache() // Tell the browser not to cache the response
redirect ( $ url , $ code = 302 ) // Redirect to the specified URL
dump ( $ obj ) // Dump an object
file ( $ path , $ filename = null ) // Send a file
json ( $ object , $ jsonp_prefix = null ) // Send an object as JSON or JSONP by providing padding prefix
$ service ->
sharedData() // Return the shared data collection
startSession() // Start a session and return its ID
flash( $ msg , $ type = ' info ' , $ params = array() // Set a flash message
flashes ( $ type = null ) // Retrieve and clears all flashes of $type
markdown( $ str , $ args , ...) // Return a string formatted with markdown
escape ( $ str ) // Escape a string
refresh() // Redirect to the current URL
back() // Redirect to the referer
query ( $ key , $ value = null ) // Modify the current query string
query ( $ arr )
layout ( $ layout ) // Set the view layout
yieldView () // Call inside the layout to render the view content
render ( $ view , $ data = array ()) // Render a view or partial (in the scope of $response)
partial ( $ view , $ data = array ()) // Render a partial without a layout (in the scope of $response)
addValidator ( $ method , $ callback ) // Add a custom validator method
validate ( $ string , $ err = null ) // Validate a string (with a custom error message)
validateParam ( $ param , $ err = null ) // Validate a param
<callback>( $ arg1 , ...) // Call a user-defined helper
<property> // Get a user-defined property
$ app ->
< callback >( $ arg1 , ...) //Call a user-defined helper
$ validator ->
notNull() // The string must not be null
isLen ( $ length ) // The string must be the exact length
isLen ( $ min , $ max ) // The string must be between $min and $max length (inclusive)
isInt() // Check for a valid integer
isFloat() // Check for a valid float/decimal
isEmail() // Check for a valid email
isUrl() // Check for a valid URL
isIp() // Check for a valid IP
isAlpha() // Check for a-z (case insensitive)
isAlnum() // Check for alphanumeric characters
contains ( $ needle ) // Check if the string contains $needle
isChars ( $ chars ) // Validate against a character list
isRegex ( $ pattern , $ modifiers = '' ) // Validate against a regular expression
notRegex ( $ pattern , $ modifiers = '' )
is<Validator>() // Validate against a custom validator
not<Validator>() // The validator can't match
<Validator>() // Alias for is<Validator>() Os testes unitários são uma parte crucial do desenvolvimento de um mecanismo de roteamento como o Klein. Recursos adicionados ou correções de bugs podem ter efeitos adversos que são difíceis de encontrar sem muitos testes, daí a importância dos testes unitários.
Este projeto usa PHPUnit como estrutura de teste unitário.
Todos os testes residem em /tests e cada teste estende uma classe abstrata AbstractKleinTest
Para testar o projeto, basta executar php composer.phar install --dev para baixar uma versão comum do PHPUnit com o compositor e executar os testes do diretório principal com ./vendor/bin/phpunit
Consulte o guia de contribuição para obter mais informações
Veja o wiki para mais informações
(Licença MIT)
Copyright (c) 2010 Chris O'Hara [email protected]
É concedida permissão, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para negociar o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar , publicar, distribuir, sublicenciar e/ou vender cópias do Software e permitir que as pessoas a quem o Software seja fornecido o façam, sujeito às seguintes condições:
O aviso de direitos autorais acima e este aviso de permissão serão incluídos em todas as cópias ou partes substanciais do Software.
O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO. EM HIPÓTESE ALGUMA OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM UMA AÇÃO DE CONTRATO, ATO ILÍCITO OU DE OUTRA FORMA, DECORRENTE DE, OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.
