Download the PHP package phpluna/framework without Composer

Luna - MVC

Luna é um framework desenvolvido em PHP com inspirações em outros frameworks como Laravel, CodeIgniter e o Express do JavaScript voltado para desenvolvimento Web com recursos como:

• Mapeamento de rotas;
• Banco de dados em ORM (Illuminate/Eloquent);
• Fila de middlewares;
• Praticidade, segurança e agilidade;
• Hospedagem simplificada;
• Armazenamento em cache;
• Componentização;
• Paginação;
• Search Engine Optimization (SEO).

Sumário

• Aprendendo Luna (Documentação)
  • Instalação
  • Inicializando
  • Rotas
    • Métodos de rota disponíveis
    • Parâmetros de rota
    • Parâmetros opcionais
    • Rotas de erros
    • Rotas de redirecionamento
  • Middlewares
  • Cross-Origin Resource Sharing (CORS)
  • Cache
  • Controllers
    • Obtendo dados da requisição
    • Respondendo a requisição
    • Tipos de resposta da requisição
  • Services
  • Helpers
  • Views
    • Padronização de página
    • Variáveis padrões
  • Flash Messages
  • Components
  • Pagination
    • Template de paginação
  • Database
    • Migrations
    • Models
  • SEO
    • Twitter e Meta OpenGraph
    • Robots
  • Environment
• Contribuindo com o projeto
• Licença

Aprendendo Luna

Instalação

Antes de iniciar seu projeto Luna, é necessário realizar a instalação do PHP (versão 7.1 ou superior) e Composer.

Utilize o comando para iniciar um projeto com Luna:

Inicializando

Renomeie o arquivo .env.example para .env e configure a URL conforme necessário:

Caso prefira, duplique o arquivo e mantenha o .env.example para que versione os exemplos de variáveis de ambiente.

As configurações gerais do projeto podem ser definidas no mesmo arquivo .env, como por exemplo a chave de autenticação de alguma API de terceiros.

Rotas

A criação de rota deve ser realizada em algum arquivo do diretório /routes (levando em consideração que você está seguindo o padrão apresentado aqui). É possível criar arquivos de separação, como pages.php para rotas de páginas ou api.php para rotas da API:

Métodos de rota disponíveis

Também é possível definir múltiplos métodos para um mesmo $uri e $callback:

Parâmetros de rota

As rotas podem receber parâmetros personalizados:

Os parâmetros podem ser obtidos na função executada:

Caso prefira, também é possível obter os parâmetros da URL através de uma variável explicita:

Parâmetros opcionais

Os parâmetros opcionais podem ser criados utilizando ?:

Parâmetros opcionais não informados na requisição serão definidos como NULL.

Rotas de erros

Alguns erros comuns podem ser tratados diretamente na definição da rota para personalizar a página de retorno:

Também é possível definir uma rota padrão para qualquer erro:

Rotas de direcionamento

Para realizar um redirecionamento em alguma rota, utilize a função redirect():

Middlewares

Os middlewares fornecem um mecanismo conveniente para validar requisições em rotas específicas:

A classe do Middleware deve conter a função handle que será executada ao acessar a rota:

A função handle deve receber os parâmetros $request, $response e $next e deve retornar $next($request, $response) para prosseguir com a fila.

Após criar a classe do Middleware, é necessário defini-lo com um apelido para que seja utilizado na definição da rota:

É possível definir middlewares padrões que serão executados em todas as rotas criadas:

Cross-Origin Resource Sharing (CORS)

O CORS pode ser configurado na inicialização da aplicação:

O Luna retornará automaticamente as requisições OPTIONS com os métodos disponíveis para uma rota.

Cache

O armazenamento do retorno de rotas em cache reduz o tempo de retorno para futuras requisições da mesma rota:

O tempo de cache é definido em milisegundos

As configurações de cache podem ser definidas no arquivo .env:

O valor de CACHE_TIME é definido como tempo de cache (também em milisegundos) quando o cache da rota for definido como true:

Controllers

As rotas executam (em sua maioria) Controllers:

Obtendo dados da requisição

Os dados da requisição como heaaders, parâmetros query, body e outros podem ser obtidos através da variável $request:

É possível obter parâmetros específicos com as funções: $request->query('id'). Não especificar um parâmetro fará com que todos sejam retornados em array.

Respondendo a requisição

Toda requisição deve ser respondida e sua resposta deve ser realizada no return da função do Controller:

Recomenda-se seguir o padrão de Status HTTP (200 no exemplo) listados aqui.

Tipos de resposta da requisição

As respostas da requisição podem retornar valores em text/html, application/json (mais comuns) ou outros (menos comuns):

É possível também utilizar alias para o retorno da requisição em HTML ou JSON:

O tipo de resposta só deve ser informado na função caso o valor de DEFAULT_CONTENT_TYPE do arquivo .env seja diferente do desejado para o Controller.

Services

Os Services auxiliam na obtenção e tratamento de dados entre o Banco de Dados e o Controller:

Uso do service:

Helpers

Um Helper agrupa pequenas funções úteis e que não são definidas como Services:

Uso do Helper:

Views

As views podem ser criadas em resources/views em .html e utilizadas na renderização:

Arquivo resources/view/page/product.html:

Para acessar diferentes níveis do array, utilize ->, por exemplo:

Obteria os valores, de:

Variáveis que não são enviadas podem receber um valor pré-definido com ??:

As variáveis da View seguem as mesmas regras dos Components, sendo assim, ambos conseguem utilizar todos os recursos.

Padronização de página

A classe Page possui funções que permitem padronizar as páginas com header, footer e outros itens padrões, alterando o valor de content:

Com uso da classe Page a variável $content irá conter a junção dos arquivos page.html, header.html e footer.html (já existentes em /resources/view).

É possíve também adicionar novos arquivos padrões para cabeçalho e rodapé, podendo por exemplo criar diferentes cabeçalhos para a área pública e área administrativa:

Para que os arquivos não sejam adicionadas, defina-o como false.

Variáveis padrões

As variáveis mais comuns podem ser definidas no arquivo index.html em View::define() e podem ser utilizadas em qualquer View:

Flash Messages

A Flash Message pode ser utilizada para retornar mensagens para a view de forma dinâmica:

Após criar uma mensagem é possível renderiza-la para adicionar em uma view:

É possível também renderizar uma mensagem que não tenha sido criada previamente:

O armazenamento das mensagens é realizado na variavel de sessão $_SESSION, não cria-la previamente pode ser útil quando a mensagem não for utilizada em outros locais.

Caso deseje, renderize diversas mensagens de uma vez (apenas para mensagens criadas previamente):

Uma vez renderizada, adicione-a na view assim como outros parâmetros:

Certifique-se de adicionar o parâmetro {{flash}} ou correspondente na view que será utilizada.

O componente das mensagens flashs pode ser alterado em /resources/components/flash/alert.html.

Se necessário, é possível criar um componente no mesmo diretório e seleciona-lo na renderização:

O valor de error presente nos exemplos é aplicado na variável {{type}} do componente e pode ser personalizado com qualquer valor para estilização.

Os tipos comuns são: error, danger, warning, info, success.

Components

Pequenas estruturas de uma view que sejam repetidas (ou não) podem ser utilizadas como um componente:

O componente deve ser criado em .html assim como a view no diretório resources/components.

É possível também criar subpastas para organizar, por exemplo: resources/components/product/card e renderizar com Component::render('product/card', $product).

Renderização múltipla

Em situações onde o mesmo componente deve ser renderizado diversas vezes a partir de um array:

Pagination

A paginação de arrays para listagem pode ser realizada com uso da classe Pagination:

A função get() retornará a lista já paginada e outros dados sobre a paginação.

É possível obter dados especificos da paginação:

Template de paginação

O controle da paginação pode ser renderizado para ser exibido na View:

Os componentes utilizados na criação da paginação podem ser modificados em resources/components/pagination e também podem ser alterados na renderização:

O href dos itens sempre utilizará o parâmetro {{page}} para definir a página destino.

Caso seja necessário remover algum item, defina o parâmetro como false.

Para limitar a quantidade de itens exibidos para cada lado do item atual, utilize:

Exemplo de resultado da renderização com 3 itens para cada lado:

Estilização deve ser realizada separadamente

Database

O acesso ao Banco de Dados de projetos Luna são realizados através do Object-Relational Mapping (ORM) utilizado no Laravel chamado Illuminate/Eloquent e o mesmo permite o uso de funções simples e rápidas para escrever querys SQLs complexas.

A configuração das credênciais de acesso ao banco de dados deve ser realizada no arquivo .env e a conexão é estabelecida com:

Ao utilizar o arquivo bootstrap.php a conexão é configurada por padrão. Ex: require __DIR__ . '/bootstrap.php';.

Acesse a documentação completo do Eloquent aqui.

Migrations

A Migration pode ser utilizada para criar modificações no banco de dados de forma programática e versionada.

Para criar uma migration, utilize o Luna CLI:

O valor name deve conter o nome do arquivo de migração, por exemplo:

É possível também criar a migration com uma tabela específica:

Para realizar a migração do banco de dados utilize o comando:

Isto irá verificar quais migrações ainda não foram executadas e executa-las.

Para executar uma migração especifica, utilize o comando:

Caso precise voltar atrás com a última migração realizada, utilize o comando:

Cada execução de migrate:rollback retornará um lote, ao executar o último lote será desfeito.

Para limpar o banco de dados e executar as migrações, utilize o comando:

Por segurança, é necessário confirmar a execução do migrate:fresh com --confirm ou -c.

Models

O Model segue o padrão do ORM Illuminate/Eloquent:

Uso do model:

SEO

O Search Engine Optimization (SEO) pode ser criado para exibição na View:

A função $seo->setKeywords() pode receber as chaves em array ou em string, como por exemplo: $seo->setKeywords("chave-1, chave-2").

Caso não utilize um título definido separadamente na renderização da view em parent::getPage utilize $seo->render(true) para que a tag <title> seja renderizada pelo SEO.

Twitter e Meta OpenGraph

A configuração para Twitter e Meta OG podem ser realizadas separadamente:

É possível configurar todas as tags separadamente para cada rede:

Caso os dados para Twitter e Meta OG sejam iguais, basta informar de uma das seguintes formas:

Caso utilize $seo->twitter() ou $seo->meta() após o uso de $seo->setTitle() e outros, as definições de título, descrição e imagem serão compartilhadas, para desativar essa função utilize $seo->twitter(false) ou $seo->meta(false) no primeiro uso de cada.

Caso a classe Seo seja inicializada sem definir o Twitter ou Meta OG o valor definido no arquivo .env em DEFAULT_SEO será utilizado.

Robots

A configuração de Robots podem ser adicionadas na renderização:

As variáveis $index e $follow devem ser Boolean.

Exemplos de de definição do Robots:

Por padrão a indexação utiliza links seguidos, então se for utilizar a função $seo->setRobots() sem passar nenhum parâmetro, ela se torna dispensável.

Environment

O arquivo .env pode ser utilizado para definir valores de configurações do projeto e podem ser obtidas em arquivos:

É possível também armazenar valores dinamicamente que não estejam presentes no arquivo .env:

Contribuindo com o projeto

Obrigado por considerar contribuir com o Luna! O guia de contribuição ainda encontra-se em desenvolvimento e em breve poderá entender como fazê-lo.

Enquanto isso, você pode realizar contribuições por conta própria no repositório.

Licença

O Luna é um software de código aberto sob a MIT License.