Help

Retour à la documentation développeur

Vue d'ensemble de Paheko

Modèle MVC

Paheko suit l'architecture MVC (Modèle Vue Contrôleur).

Les objets métiers (business objects) héritent de Garradin/Entity qui hérite lui-même de KD2\DB\AbstractEntity.

Les contrôleurs ne sont pas des objets mais de simples scripts PHP procéduraux (ex : www/admin/login.php) qui utilisent les objets techniques (ex : Garradin\Users\Session).

La vue côté Administration/Back-office mon-site.paheko.cloud/admin est gérée par Smartyer, sauf pour les modules pour lesquels elle est gérée par Brindille.
La vue côté Site web/front-office mon-site.paheko.cloud est gérée par Brindille.

  • Smartyer utilise des fichiers templates avec l'extension .tpl.
  • Brindille ne traite que les fichiers avec une des extensions tpl, btpl, html, htm, b, skel, xml. Généralement les pages publiques d'un module utilisent l'extension .html.

Il n'est donc pas possible de différencier un template smartyer d'un template Brindille par son extension.

Vue

Le javascript principal de l'administration est www/admin/static/scripts/global.js.

La feuille de style CSS principale de l'administration est www/admin/static/admin.css.

Les variables de base sont listées ici : Référence des variables définies par défaut.

Classes CSS principales

  • confirm block : pour confirmer la soumission d'un formulaire. 
    <p class="confirm block">Membre inscrit·e avec succès.</p>
  • error block : pour un block de message(s) d'erreur 
    <p class="confirm block">Cette personne est déjà inscrite.</p>
  • alert block : pour un avertissement 
    <p class="confirm block">Certaines options nécessitent une configuration.</p>
  • help block : pour afficher un block de message 
    <p class="help block">Ne sont affiché·e·s que les membres des catégories publiques.</p>
  • infos : pour de l'espacement (pour la lisibilité) sous un block
  • ruler : départage deux sections d'une page 
    <h2 class="ruler">Liste des activités des membres</h2>
  • list : pour les tableaux de données 
    <table class="list">
  • num : pour les colonnes contenant un numéro que l'on souhaite mettre en valeur 
    <td class="num">{{$user.numero}}</td>
  • money : préserve le formatage d'une somme
  • hidden : cache la balise au chargement de la page (souvent utilisé en conjonction avec g.toogle()) 
    <div class="hidden" id="advanced_input">
    {{input type="select" ...}}
</div>

Fonctions javascript principales

  • $(string my_selector) : sélectionne un élément à la manière de jQuery. my_selector peut donc être un ID si précédé d'un #, une classe si précédé d'un . (point), autrement c'est le nom d'une balise.
    Les syntaxes complexes sont supportées.
console.log( $('#my_input').value );

$('td.num').forEach( (e) => { console.log(e); } );

$('form .input-list > button[required]')
  • querySelectorAll : à documenter
  • g.toogle(string item, bool visibility) : change la visibilité d'un élément
g.toogle('#advanced_input', true);

g.toogle('#advanced_input', $('#advanced_mode_checkbox').checked);

Controller

Tous les contrôleurs s'initialisent en appelant include/init.php (qui charge également le fichier de configuration config.local.php (créé à l'installation)).

Les contrôleurs de l'administration chargent à la place www/admin/_inc.php (qui appelle lui-même include/init.php).
C'est lui qui instancie les globales $tpl, $session, $config et $form (respectivement Garradin\Template, Garradin\Users\Session, Garradin\Config et Garradin\Form).

Fonctions principales

  • qg(string $var_name) : récupère un élément dans le $_GET s'il existe, renvoi null autrement.
    Disponible uniquement pour les controleurs de l'admin.
// admin/users/details.php?id=17

$id_user = qg('id');
  • $form->runIf(string $post_var, callback $function, ?string $csrf_key, ?string $url) : exécute la fonction $function si $post_var est présent dans $_POST et redirige ensuite sur $url.
    Dans le cas où une erreur (c-à-d une Exception) survient le processus est interrompu et donc la redirection ne se fait pas et Paheko affiche l'erreur sur la page courante.
$form->runIf('add_family_member', function () use ($session) {
        $user = $session->getUser();
        [...]
}, $csrf_key, '?ok=1');
  • $tpl->assign() : assigne des variables aux templates (cf. Documentation smarty de assign)
  • $tpl->display(string $template) : affiche le template $template
// From a core controller
$tpl->display('users/details.tpl');

// From a plugin controller
$tpl->display(PLUGIN_ROOT . '/templates/index.tpl');

Arborescence des fichiers

Main

  • include/data/schema.sql => Database creation SQL script | const DB_SCHEMA
  • data/association.sqlite => Database file | const DB_FILE
  • include/lib/Garradin/Entities/ => Business objects
  • include/lib/Garradin/ => Technical objects
  • www/admin/ => Controllers (Back-office)
  • www/admin/static/ => Static back-office content (CSS, JavaScript, images...)
  • data/plugins/ => Paheko Plugins | const PLUGINS_ROOT
  • templates/ => View (Back-office)
  • modules/web/ => View (Front-office)
  • modules/ => Paheko Modules

Others

  • data/cache => Template compilation cache | const CACHE_ROOT
  • scripts => Standalone scripts
  • data/error.log => Errors log file
  • debug_sql.sqlite => SQL queries logs' database (existing only if specified by SQL_DEBUG)

Constantes correspondantes

  • ROOT
  • DATA_ROOT

  • CACHE_ROOT, SHARED_CACHE_ROOT, WEB_CACHE_ROOT, USER_TEMPLATES_CACHE_ROOT, STATIC_CACHE_ROOT, SHARED_USER_TEMPLATES_CACHE_ROOT, SMARTYER_CACHE_ROOT

  • WWW_URI

  • WWW_URL

  • ADMIN_URL

Ces constantes sont définies dans include/init.php et peuvent être surchargées dans config.local.php.

Schéma de la base de données

Depuis la version 1.3.7, le schéma interactif est visible dans Configuration > Fonctions avancées > SQL > Schéma.

Compartimentation

Le cœur de Paheko peut être augmenté de fonctionnalités via deux moyens : les extensions/plugins et les modules.

Les extensions se greffent (avec processus d'installation et de désinstallation) sur le logiciel.

Les modules s'activent ou se désactivent mais ne comportent pas de processus d'installation et ne contiennent pas de PHP.

Debuggage

Logging global

De base, toutes les erreurs et exceptions PHP et Brindille sont logguées dans data/error.log, sous la forme :

[12-Apr-2023 10:53:49 Europe/Berlin] =========== Error ref. 2ockkq2h ===========

Error: Call to a member function assign() on int in /home/alinaar/paheko/dev_branch/src/www/admin/index.php:28
Stack trace:
#0 {main}

<errorReport>
{
    "errors": [
        {
            "message": "Call to a member function assign() on int",
            "errorCode": 0,
            "type": "PHP error",
            "backtrace": [
                {
                    "file": "...\/www\/admin\/index.php",
                    "line": 28,
                    "code": {
                        "24": "}",
                        "25": "",
                        "26": "$buttons = Plugins::listModulesAndPluginsHomeButtons($session);",
                        "27": "$tpl = 17;",
                        "28": "$tpl->assign(compact('homepage', 'banner', 'buttons'));",
                        "29": "",
                        "30": "$tpl->assign('custom_css', ['!web\/css.php']);",
                        "31": "",
                        "32": "$tpl->display('index.tpl');"
                    }
                }
            ]
        }
    ],
    "context": {
        "date": "2023-04-12T10:53:49+02:00",
        "duration": 8.744001388549805,
        "environment": "development",
        "garradin_data_root": "\/home\/alinaar\/paheko\/dev_branch\/src\/data",
        "garradin_version": "1.3.0-alpha1",
        "hostname": "dev.paheko.fr",
        "http_files": "array(0) {\n}",
        "http_method": "GET",
        "http_post": "array(0) {\n}",
        "http_referrer": "https:\/\/dev.paheko.fr\/admin\/login.php",
        "http_user_agent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/109.0.0.0 Safari\/537.36",
        "id": "2ockkq2h",
        "language": "PHP 7.4.33",
        "memory_peak": 2097152,
        "memory_used": 2097152,
        "os": "Linux",
        "php_sapi": "apache2handler",
        "remote_ip": "127.0.0.1",
        "root_directory": "\/home\/alinaar\/paheko\/dev_branch\/src",
        "server_addr": "127.0.0.1",
        "user_addr": "127.0.0.1",
        "url": "https:\/\/dev.paheko.fr\/admin\/"
    }
}
</errorReport>

Ces données sont disponibles de manière lisible dans Configuration > Fonctions avancées > Journal d'erreurs (https://mon-asso.org/admin/config/advanced/errors.php).

Logging SQL

Pour activer le log des requêtes SQL - qui se fera sous forme d'entrées dans une base de données SQLite - il faut définir la constante SQL_DEBUG avec comme valeur le chemin de la BDD de log désirée.

Le fichier config.dist.php propose de décommenter la ligne suivante : 

const SQL_DEBUG = __DIR__ . '/debug_sql.sqlite';
Attention : dans ce cas la BDD de log SQL sera donc à la racine du site (/debug_sql.sqlite) et non pas dans le répertoire data comme pour le fichier /data/error.log !

Ces données sont visualisables dans Configuration > Fonctions avancées > Journal SQL (https://mon-asso.org/admin/config/advanced/sql_debug.php) si vous avez mis la constante ENABLE_TECH_DETAILS à true.
Note : cette page n'étant pas paginée, elle peut être très longue à charger si vous avez activé les logs SQL depuis le début de votre développement.

Verbose global

Pour faciliter le debuggage, les constantes suivantes peuvent être modifiées dans le fichier config.local.php (voir la documentation complète dans config.dist.php) : 

const SHOW_ERRORS = true;
const REPORT_USER_EXCEPTIONS = 2;
const SQL_DEBUG = __DIR__ . '/debug_sql.sqlite';
const ENABLE_TECH_DETAILS = true;

const MAIL_ERRORS = 'dev@mon-asso.org';
const ERRORS_REPORT_URL = 'https://error-recorder.mon-asso.org';
const HTTP_LOG_FILE = __DIR__ . '/http.log';

Verbose local

Il est possible de rajouter un paramètre debug=true aux sections brindilles suivantes {{#select}}, {{#sql}}, {{#load}} et {{#list}} pour afficher la requête executée.

Debuggage à la main

En brindille il est possible d'afficher le contenu et le type d'une variable (équivalent de var_dump()) via la fonction {{:debug}}.
L'équivalent existe en Smartyer avec le modifier dump : 

{$my_var|dump}

Pour arrêter le script brindille, la fonction {{:error}} peut être utilisée.

Exceptions

Liste des exceptions utilisées :

  • InvalidArgumentException
  • UnexpectedValueException
  • BadFunctionCallException
  • LengthException
  • OverflowException
  • OutOfBoundsException
  • RuntimeException
  • LogicException
  • Garradin\UserException : pour les erreurs de saisie utilisateur/trice par exemple
  • Garradin\ValidationException : throw par les validations des propriétés et méthodes métier des Entity
  • Garradin\APIException
  • KD2\Brindille_Exception
  • KD2\Smartyer_Exception
  • KD2\DB\DB_Exception
  • PDOException
  • KD2\WebDAV\Exception
  • IntlException

Rédaction en cours...

À documenter notamment :

  • stockage des articles et documents du site web
  • routage des URL
  • gestion des exceptions (+ lister les types d'exception utilisés)
  • fichiers de log
  • gestion des droits d'accès back-office $session->canAccess() et {{#restrict}}
  • fichiers/répertoires avec droits en écriture
  • liste des constantes
  • méthodes pour contacter la BDD et faire des requêtes
  • Services/Helpers et Entities
  • DynamicFields

Attachments:

  • schema_2022-02-08-v1.3.png [download] added by bohwaz on 2023-02-08 13:55:34. [details]
  • schema_2022-02-08-v1.3.svg [download] added by bohwaz on 2023-02-08 13:46:47. [details]