Getting started
Project structure
Overview
project/
├── .htaccess forwards everything to webroot/
├── composer.json Smarty 4, Pusher, PhpSpreadsheet
├── app/
│ ├── bin/ scripts: setup.sh, warm-cache, create-plugin.sh, build-docs.py
│ └── docs-src/ Markdown sources of this documentation
├── config/ global configuration
│ ├── config.php, datasources.php, cache.php, sessions.php,
│ │ extensions.php, rewrite.php, i18n.php, email.php
│ ├── locales/{es,en,pt}/*.json core translations
│ └── domains/<domain>/ per-domain overrides
├── core/ the framework (not modified per project)
├── src/ the application code
├── plugins/<name>/ optional modules
├── webroot/ the only folder served to the browser
│ ├── index.php entry point
│ ├── js/, css/, img/ shared assets
│ └── themes/<theme>/ templates and assets of each theme
├── tmp/ cache/, logs/, sessions/ (writable)
└── vendor/ Composer dependencies
core/: the framework
| Folder | Contents |
|---|---|
Koshkil.php |
Central static class: file loading, configuration, links, saved POST data. Including it loads the configuration and registers the error handler. |
KoshkilApplication.php |
Main loop: run() parses the route, invokes the action and renders the response. |
http/ |
Route, RewriteManager, Request, Response, Session (and session/DatabaseSession), WebElements. |
web/ |
Controller, AjaxController, JavascriptController, View, TWidget, ActionDispatcher, Controller/Component, Plugins/PluginsManager, Rest/. |
db/ |
TModel, TQueryBuilder, Manager (schema sync), schema/ (table definitions), traits/ (hierarchy, ordering, ownership, translation, multimedia), drivers/. |
models/ |
Core models: users, roles, rules, profiles, sessions, gallery, languages… |
cache/ |
CacheManager and the File, Redis and Null engines. |
tools/ |
Configure, I18n, Inflector, TCollection, KoshkilLog, Profiler, Sanitize and utils/ (dates, strings, files, images, email…). |
exceptions/ |
ExceptionRenderer (global handlers) and custom exceptions. |
events/ |
TEventManagerTrait, the model event system. |
network/ |
curl and ftp clients. |
library/ |
Bundled libraries (PHPMailer). |
src/: the application
| Path | Role |
|---|---|
Application.php |
Extends KoshkilApplication. Initializes the cache in startup(). |
SuperController.php |
Base for public-site controllers (templateFolder = "front", open access, session user). |
AdminSuperController.php |
Base for the admin panel (templateFolder = "admin", login required, menu, inspinia theme). |
FrontAjaxController.php, AdminAjaxController.php |
Bases for JSON responses. |
FrontJavascriptController.php, AdminJavascriptController.php |
Bases for server-generated JavaScript. |
Controllers/ |
Controllers. Sub-folders are part of the URL (Ajax/, Admin/, Js/…). |
Controllers/Components/ |
Components shared between controllers. |
Models/ |
The project's own models (looked up before core/models/). |
Widgets/ |
Widgets (front/THeader.php, admin/TUploads.php…). |
Smarty/plugins/ |
Custom Smarty functions, blocks and modifiers. |
api/ |
REST API endpoints (usuarios.php → usuarios.* actions). |
Migrations/ |
Versioned SQL scripts (see Models). |
Koshkil::Uses() namespaces
Koshkil does not use PHP namespaces or an autoloader of its own: each file is included with a dotted path.
| Prefix | Folder | Example | File |
|---|---|---|---|
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'); // second argument: fallback
Uses() returns true when it finds the file. Models and behaviors have shortcuts that also create class aliases: Koshkil::UsesModel() and Koshkil::UsesBehavior().
Naming
| Item | Convention | Example |
|---|---|---|
| Controller | <Name>Controller in src/Controllers/<Name>Controller.php |
CuentasController |
| Action | public method; the URL reset-password calls resetPassword() |
/cuentas/reset-password |
| Model | class TModel<Name> in Models/<name>.php, alias TM<Name> |
TModelUsuarios / TMUsuarios |
| Widget | class T<Name> in Widgets/<group>/T<Name>.php, template widgets/<group>/<name>.tpl |
THeader |
| API endpoint | class <Class>ApiController in src/api/<class>.php |
UsuariosApiController |
| Table | tbl_ prefix; columns with a 3-letter prefix |
tbl_usuarios.usr_email |