Download the PHP package atomdev/odinfmk without Composer

Bem-vindo à Ødin!

Ødin é uma Framework do PHP simples, prática e eficiente. Desenvolvida para se fazer mais e escrever menos. Se ainda não tem uma licença, contate-nos em [email protected].

Documentação

Instalação

Instale a Ødin através do Composer.

composer require atomdev/odinfmk

Iniciando um projeto

Primeiramente você deve definir as constantes ODIN_SERIAL e ODIN_ROOT no arquivo de autoload do Composer (vendor/autoload.php).

Em seguida, na raiz do seu projeto, você deve definir a estrutura base do projeto.

config/
   |-- .env
http/
    controllers/
       |-- Aqui ficarão seus Controllers
    middlewares/
       |-- Aqui ficarão seus Middlewares
database/
    models/
       |-- Aqui ficarão seus Models
views/
   |-- Aqui ficarão suas views
utils/
   |-- Aqui ficarão suas classes de utilidades e seus Helpers
.htaccess

Vale ressaltar que a estrutura apresentada acima é apenas o modelo base padrão. Você pode criar suas pastas personalizadas além das mostradas acima.

Definindo as configurações do projeto

Na pasta de config, você deverá criar um arquivo chamado .env. Este será o arquivo de configurações do projeto. Nele será definido o ambiente, o SGBD, os diretórios e url de acesso do projeto. Veja o seguinte modelo:

ENVIRONMENT     = dev
DRIVER          = mysql
SOURCE_DIR      = src/
HTTP_ROOT   = http://localhost:8080
HTTP_ROOT_FILES = http://localhost:8080/assets/ 

Você pode utilizar de dois ambientes Desenvolvimento e Produção utilizando a constante ODIN_ENV junto de ODIN_ROOT e ODIN_PATH, ao definir como dev um arquivo chamado dev.env deverá ser criado na pasta de configurações com as diretivas de desenvolvimento enquanto o .env passa a ser as diretivas de produção.

Definindo as rotas da aplicação

Antes de definir suas rotas você precisa configurar o .htaccess localizado na raiz do projeto. Ao abrir você encontrará a seguinte estrutura:

RewriteEngine On
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [QSA,L]

ErrorDocument 403 http://localhost/pagina/de/erro/403
Options All -Indexes

Você pode definir uma página para tratamento dos erros 403, que são lançados quando o usuário tenta acessar pastas proibidas. Por padrão, todas as pastas da aplicação têm o acesso proibido a abertura via HTTP.

Após configurar o .htaccess você poderá definir suas rotas no arquivo index.php, como no exemplo a seguir.

A Ødin suporta 4 tipos de Requisições HTTP, sendo elas GET, POST, PUT e DELETE. Isso dá a você total facilidade e praticidade na hora de criar uma RESTful API.

Controllers

Os controllers são Callables que são passados para as rotas para que alguma ação seja feita caso acessada. Você pode criar um controller para um rota de duas formas

Forma funcional:

Forma Orientada a Objetos:

Routes::get("/teste", "App\http\controllers\Teste:olaMundo");

Para a forma OO, você precisa ter criado uma classe dentro da pasta controllers de acordo com o exemplo abaixo.

        </tbody>
    </table>
</div>

Utilizando desta mesma propriedade, você pode recuperar o URL de qualquer rota que você tenha definido em suas Views, facilitando a navegação entre diversas páginas. Mas para isso você precisa passar o objeto router como uma variável para a View.

public function view()
{
    View::render($this, "login_page.php", [
        "router" => $this->router
    ]);
}

Na view:

<a href="<?= $router->pathFor("loginPage") ?>">Login Page</a>

Caso sua rota seja dinâmica e seja necessário passar um valor, você pode passar as referências no segundo parâmetro do método pathFor().

<a href="<?= $router->pathFor("listarFilmes", ["categoria" => "terror"]) ?>">Login Page</a>

Objetos de escopo Global (Dependencias)

Caso sua view necessite acessar algum objeto de alguma classe utils ou algum helper, você pode definir objetos de escopo global no arquivo index.php como mostra o exemplo a seguir.

use Odin\Globals;

Globals::set([
    new Helper(),
    new Dependencia()
]);

Na view, você pode acessar esses objetos passados como dependencias da seguinte forma:

<div>
    <?= $helper->someMethod() ?>
    <?= $dependencia->algumaCoisa() ?>
</div>

Middlewares

A Ødin também oferece suporte a Middlewares, de maneira bem prática e simples, como no exemplo a seguir.

namespace App\http\middlewares;

use Odin\http\middleware\IMiddleware;
use Odin\utils\superglobals\Session;

class Auth implements IMiddleware
{
    public function handle($request, $response, $next)
    {
        if(Session::exists("_token"))
        {
            return $next($request, $response);
        }
        else
        {
            die("Você precisa fazer login para acessar esta página");
        }
    }
}

No index.php você define a lista de Middlewares através do método add().

Routes::add(["home"], [
    new Auth()
]);

Routes::get("/home", "App\http\controllers\Home:landing")->name("home");

Você pode adicionar Middlewares a rotas, names e groups. Para adicionar uma Middleware a todas as rotas basta usar ["*"].

Models

CRUD

Antes de começar a usar os Models em seu projeto, certifique-se de que está definida a diretiva DRIVER em config/.env , e, se há um arquivo com os dados da conexão na mesma pasta. Ex: config/mysql.env ou config/pgsql.env

DRIVER          = mysql
HOST            = 127.0.0.1
USERNAME        = root
PASSWORD        = root
PORT            = 3306
SCHEMA          = dbname

Para utilizar Models em seu projeto, basta criar uma classe na pasta database/models e atribuir a ela a seguinte estrutura.

namespace App\database\models;

use Odin\database\orm\ORMMapper;

class SimpleModel extends ORMMapper
{
    private $tableName = "teste";

    public function __construct()
    {
    parent::__construct();
    parent::setTableName($this->tableName);
    }
}

Select

Recuperando todos os registros existentes na tabela

use App\database\models\SimpleModel;

$model = new SimpleModel();

var_dump($model->findAll());

Recuperando um registro pelo id

$model->findById(10);

Recuperendo registros com a claúsula WHERE

$model->where(["id" => 10], ">")->get(); // id > 10

$model->where(["id" => [10, 20]], "BETWEEN")->get(); // id BETWEEN 10 AND 20
$model->where(["id" => [10, 20]], "NOT BETWEEN")->get(); // id NOT BETWEEN 10 AND 20 

$model->where(["name" => "User"], "LIKE")->get(); // name LIKE '%User%'
$model->where(["name" => "user"], "LIKE_L")->get(); // name LIKE '%User'
$model->where(["name" => "user"], "LIKE_R")->get(); // name LIKE 'User%'

$model->where(["id" => [1, 2, 3, 4, 5]], "IN")->get(); // id IN (1,2,3,4,5)
$model->where(["id" => [1, 2, 3, 4, 5]], "NOT IN")->get(); // id NOT IN (1,2,3,4,5)

$model->where(["id" => "NULL"], "IS")->get(); // id IS NULL

Recuperando campos específicos com get()

$model->where(["id" => 10], "<=")->get("id, name, age");

Ordenando registros com ORDER BY

$model->where(...)->orderBy("id", "ASC")->get();

Agrupando registros

$model->where(...)->groupBy("id")->get();

$model->where(...)->groupBy("id")->having(...)->get();

Insert

Para inserir registros, basta você adicionar novas propriedades ao objeto do Model e usar o método save().

$model->name = "New User";
$model->email = "[email protected]";
$model->age = 20;

$model->save();

O método save deve retornar um PDOStatement em caso de sucesso, ou false em caso de falha ao inserir o novo registro.

Update

Para realizar um update, você vai utilizar a mesma estrutura do insert, contudo, o id deverá ser informado. Ele é a chave para a diferenciação de comando INSERT de um UPDATE.

$model->id = 25;
$model->name = "Name Updated";

$model->save();

Delete

Para realizar um DELETE você deverá primeiro recuperar o registro que deseja excluir e usar o método remove(). Como no exemplo abaixo.

$model->findById(10)->remove();

Joins

Você pode adicionar Alias às tabelas para facilitar seu uso, como no exemplo a seguir.

class SimpleModel extends ORMMapper
{
   private $tableName = "teste";
   private $tableAlias = "t";

   public function __construct()
   {
    parent::__construct();
    parent::setTableName($this->tableName, $this->tableAlias);
   }
}

E usá-lo da seguinte forma

$model->innerJoin("another a")->on("a.id = t.fk")->get();
$model->leftJoin("another a")->on("a.id = t.fk")->get();
$model->rightJoin("another a")->on("a.id = t.fk")->get();

$model->innerJoin("another a")
    ->on("a.id = t.fk")
    ->where(["id" => 10], ">=")
    ->get();

Utilidades

Flash Messages

A classe Odin\utils\FlashMessages permite a você definir mensagens que se autodestroem após as visualização, esse recurso pode ser utilizado para a implementação de notificação em tempo de aplicação, veja o seguinte exemplo.

public function simpleMethod()
{
    //Define uma nova mensagem
    FlashMessages::add("Teste", "Testando mensagens flash");

    //Recupera o valor da mensagem
    echo FlashMessages::get("Teste");

    //Verifica se há uma mensagem na chave informada
    var_dump(FlashMessages::has("Teste"));
}

Superglobais

O namespace Odin\utils\superglobals contém classes para manuseamento das superglobais nativas do PHP ($_GET, $_POST, $_SERVER, $_SESSION, $_COOKIE e $_FILES).

Veja o exemplo abaixo.

use Odin\utils\superglobals\Post;
use Odin\utils\FlashMessages;

class Teste extends Controller
{
    public function autenticar()
    {
        $usuario = Post::get("usuario");
        $senha = Post::get("senha");

        if($usuario === "user" && $senha === "pass")
        {
            FlashMessages::add("Sucesso", "Autenticação realizada com sucesso!");
            $this->router->redirectTo("home");
        }
        else
        {
            FlashMessages::add("Erro", "Não foi possível realizar a autenticação");
            $this->router->redirectTo("login");
        }
    }
}

Filtros de Dados

A classe Odin\utils\Filter fornece uma série de métodos para a realização da filtragem de dados, sejam senhas, emails ou textos comuns.

use Odin\utils\Filter;
...
public function filtrarDados()
{
    $email = Filter::email(Post::get("email"));
    $senha = Filter::clear(Post::get("senha"));

    var_dump(Filter::isValidEmail($email));
}

Headers

Você também pode gerenciar os Headers das suas requisições com a classe Odin\http\server\Header.

use Odin\http\server\Header;
...
public function getDataAsJSON()
{
    Header::contentType("application/json");

    return [
        ["name" => "John", "age" => 20],
        ["name" => "Doe", "age" => 22]
    ];
}

Enviando Emails

Você pode enviar emails nativamente pela função mail de forma mais simples utilizando a classe Odin\utils\Mail, como mostra o exemplo.

public function enviarEmail()
{
    Mail::from("[email protected]");
    Mail::write("[email protected]", "Teste de Envio de Email");
    Mail::headers();
    Mail::message("<b>Hey! Testando envio de email pela Ødin!</b>");

    echo (Mail::send() ? "Email enviado." : "Email não enviado.");
}

Collections

As Collections são classes que implementam estruturas de dados baseadas em linguagens fortemente tipadas como Java e C#, e foram implementas para facilitar a manipulação de arrays de objetos, ou seja, todas as Collections contidas em Odin\utils\collections devem ser utilizadas com objetos. Nesta versão da Ødin, há 3 Collections implementadas, são elas: ArrayList, Dictionary e Queue.

ArrayList

O ArrayList agrupa vários objetos como se fosse um array de chaves numéricas, como no exemplo abaixo, entretanto de forma orientada a objetos e mais organizada e fácil de manipular.

$array = [
    0 => new Usuario()
];

Usando o ArrayList:

use App\classes\Usuario;
use Odin\utils\collections\ArrayList;
use Odin\utils\Functions;

$arraylist = new ArrayList(Usuario::class);

$arraylist->add(new Usuario());

Functions::debug($arraylist->get(0));

Dictionary

O Dictionary é uma estrutura de chave-valor, ou seja, é necessário informar uma chave do tipo string e um valor sendo um objeto, como se fosse um array com chaves não-numericas, como no exemplo abaixo:

$array = [
    "nome" => "Odin"
    "tipo" => "Framework"
];

Usando o Dictionary:

use App\classes\Usuario;
use Odin\utils\collections\Dictionary;

$dictionary = new Dictionary("string", Usuario::class);
$dictionary->add("user1", new Usuario());
$dictionary->add("user2", new Usuario());

echo $dictionary->toJson();

Queue

A Queue é uma fila, ou seja, o primeiro elemento a ser inserido será o primeiro a sair, não há como recuperar um elemento de um determinado índice ou por chave, sempre será de forma ascendente ou descendente.

use App\classes\Animal;
use Odin\utils\collections\Queue;

$queue = new Queue(Animal::class);

$queue->add(new Animal("Bolt"));
$queue->add(new Animal("Max"));

\Odin\utils\Functions::debug($queue->peek());