DocumentationFor DevelopersProgramming Guidelines

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.

Shared PHP APIs

Core namespace files own reusable behavior for their domain. In particular, use Latch\File for filesystem paths and traversal, Latch\Http for request and URL comparisons, Latch\Environment for normalized PHP configuration values, Latch\Apache for managed Apache configuration blocks, Latch\Html for HTML and inline-script encoding, and Latch\Metadata for persisted metadata and tag decoding. Feature classes should retain policy and lifecycle decisions while delegating generic operations to these shared APIs.

Latch\Metadata\decode() accepts an array, ordinary JSON, or the historically HTML-entity-encoded JSON found in older records. Latch\Metadata\tags() returns canonical tag records containing a non-empty string value; Latch\Metadata\tag_values() returns only those string values.

New class and namespace files should briefly state their responsibility when the boundary is not obvious. Document shared APIs when callers need to understand accepted representations, normalization, side effects, return shapes, failure behavior, or security constraints. Avoid comments that simply repeat a clear signature.

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.