Programming Guidelines

Naming Conventions

The Latch codebase follows these naming conventions:

Variable and function names use snake_case.
Classes and namespaces use PascalCase.
Indentation uses tabs.
PHP uses Allman braces.
PHP formatting should stay compatible with Intelephense.
HTML and CSS use dash-separated-names where those names become public web-facing identifiers.
Object names within Latch, such as form names or menu names, are expected to be unique. Use clear title-style names for admin-facing objects.

In situations where long-form HTML is echoed from a PHP file, Heredoc encapsulation is preferred:

<?php

if (Latch\Session\is_role("Administrator"))
{
    $some_var = "abc";
    $another_var = 123;

    echo <<<HTML
        <li>$some_var</li>
        <li>$another_var</li>
    HTML;
}

Variable Shorthand Definitions

ev: Event.
el: Element.
sel: Selector.

Browser Request Security

Latch uses a synchronizer token stored in the active PHP session to protect browser requests that change server state. Password-reset, email-verification and CAPTCHA tokens have separate purposes and must not be reused as CSRF tokens.

AJAX actions loaded through app/controller.php are protected centrally. Calls made through Latch.App.do_ajax() attach the current token automatically, including FormData uploads. Extension AJAX handlers must not add their own origin or token checks unless they have a separate security requirement.

Forms rendered by Latch\Echo\form() receive a hidden CSRF field automatically. A manually rendered form must include the shared field:

<form action="..." method="post">
    <?= Latch\Session\csrf_field(); ?>
    ...
</form>

Its POST handler must validate the request before performing any mutation:

if (($_SERVER["REQUEST_METHOD"] ?? "") === "POST")
{
    Latch\Session\require_csrf_token();
    // Process the verified request.
}

Use Latch\Session\require_csrf_token(json_response: true) for a direct browser endpoint that returns JSON. The shared validator checks the session token and also rejects a mismatched Origin or Referer when the browser supplies one.

Do not call CSRF validation from database helpers, event handlers, background cron invocations or signed webhooks. CSRF protects cookie-authenticated browser intent; server-to-server routes must use their own authentication, such as a webhook signature.