Primeiros passos
Estrutura do projeto
Visão geral
projeto/
├── .htaccess encaminha tudo para webroot/
├── composer.json Smarty 4, Pusher, PhpSpreadsheet
├── app/
│ ├── bin/ scripts: setup.sh, warm-cache, create-plugin.sh, build-docs.py
│ └── docs-src/ fontes Markdown desta documentação
├── config/ configuração global
│ ├── config.php, datasources.php, cache.php, sessions.php,
│ │ extensions.php, rewrite.php, i18n.php, email.php
│ ├── locales/{es,en,pt}/*.json traduções do núcleo
│ └── domains/<domínio>/ sobrescritas por domínio
├── core/ o framework (não se altera por projeto)
├── src/ o código da aplicação
├── plugins/<nome>/ módulos opcionais
├── webroot/ a única pasta servida ao navegador
│ ├── index.php ponto de entrada
│ ├── js/, css/, img/ recursos comuns
│ └── themes/<tema>/ templates e recursos de cada tema
├── tmp/ cache/, logs/, sessions/ (gravável)
└── vendor/ dependências do Composer
core/: o framework
| Pasta | Conteúdo |
|---|---|
Koshkil.php |
Classe estática central: carga de arquivos, configuração, links, POST salvo. Ao incluí-la, a configuração é carregada e o manipulador de erros é registrado. |
KoshkilApplication.php |
Ciclo principal: run() interpreta a rota, invoca a ação e renderiza a resposta. |
http/ |
Route, RewriteManager, Request, Response, Session (e session/DatabaseSession), WebElements. |
web/ |
Controller, AjaxController, JavascriptController, View, TWidget, ActionDispatcher, Controller/Component, Plugins/PluginsManager, Rest/. |
db/ |
TModel, TQueryBuilder, Manager (sincronização do esquema), schema/ (definição de tabelas), traits/ (hierarquia, ordem, propriedade, tradução, multimídia), drivers/. |
models/ |
Modelos do núcleo: usuários, papéis, regras, perfis, sessões, galeria, idiomas… |
cache/ |
CacheManager e os motores File, Redis e Null. |
tools/ |
Configure, I18n, Inflector, TCollection, KoshkilLog, Profiler, Sanitize e utils/ (datas, strings, arquivos, imagens, e-mail…). |
exceptions/ |
ExceptionRenderer (manipuladores globais) e exceções próprias. |
events/ |
TEventManagerTrait, o sistema de eventos dos modelos. |
network/ |
Clientes curl e ftp. |
library/ |
Bibliotecas incluídas (PHPMailer). |
src/: a aplicação
| Caminho | Papel |
|---|---|
Application.php |
Estende KoshkilApplication. Inicializa o cache em startup(). |
SuperController.php |
Base dos controladores do site público (templateFolder = "front", acesso aberto, usuário da sessão). |
AdminSuperController.php |
Base do painel (templateFolder = "admin", exige login, menu, tema inspinia). |
FrontAjaxController.php, AdminAjaxController.php |
Bases para respostas JSON. |
FrontJavascriptController.php, AdminJavascriptController.php |
Bases para JavaScript gerado no servidor. |
Controllers/ |
Controladores. As subpastas fazem parte da URL (Ajax/, Admin/, Js/…). |
Controllers/Components/ |
Componentes compartilhados entre controladores. |
Models/ |
Modelos próprios do projeto (buscados antes dos de core/models/). |
Widgets/ |
Widgets (front/THeader.php, admin/TUploads.php…). |
Smarty/plugins/ |
Funções, blocos e modificadores de Smarty próprios. |
api/ |
Endpoints da API REST (usuarios.php → ações usuarios.*). |
Migrations/ |
Scripts SQL versionados (veja Modelos). |
Namespaces de Koshkil::Uses()
O Koshkil não usa namespaces do PHP nem autoload próprio: cada arquivo é incluído com um caminho com pontos.
| Prefixo | Pasta | Exemplo | Arquivo |
|---|---|---|---|
sys. |
core/ |
sys.http.Route |
core/http/Route.php |
com. |
src/ |
com.SuperController |
src/SuperController.php |
plugins.<p>. |
plugins/<p>/src/ |
plugins.noticias.Models.noticias |
plugins/noticias/src/Models/noticias.php |
Koshkil::Uses('sys.tools.utils.fileUtils');
Koshkil::Uses('com.Widgets.front.THeader');
Koshkil::Uses('com.Models.productos', 'sys.models.productos'); // segundo argumento: alternativa
Uses() retorna true se encontrou o arquivo. Para modelos e comportamentos há atalhos que também criam apelidos de classe: Koshkil::UsesModel() e Koshkil::UsesBehavior().
Nomenclatura
| Elemento | Convenção | Exemplo |
|---|---|---|
| Controlador | <Nome>Controller em src/Controllers/<Nome>Controller.php |
CuentasController |
| Ação | método público; a URL reset-password chama resetPassword() |
/cuentas/reset-password |
| Modelo | classe TModel<Nome> em Models/<nome>.php, apelido TM<Nome> |
TModelUsuarios / TMUsuarios |
| Widget | classe T<Nome> em Widgets/<grupo>/T<Nome>.php, template widgets/<grupo>/<nome>.tpl |
THeader |
| Endpoint da API | classe <Classe>ApiController em src/api/<classe>.php |
UsuariosApiController |
| Tabela | prefixo tbl_; colunas com prefixo de 3 letras |
tbl_usuarios.usr_email |