Preventing URL Invocation

Sometimes, you may have code that should never be invoked by navigating to a particular URL. For those situations, Trongate v2 offers the block_url() function.

With block_url(), you explicitly declare which module (or module/method combination) should be blocked from URL access, and the framework enforces it.

How The block_url() Helper Function Works

The block_url() helper function accepts a string that identifies the module or module-method pair you wish to protect.

The function accepts one argument - a string that represents one of the following:

1. 'module' - blocks all methods in the module from URL access
2. 'module/method' - blocks only that method from URL access

The helper compares the supplied $block_path against the current URL segments and returns a 403 Forbidden response when a match is detected.

Blocking a Single Method

To block browser access to a specific method, call block_url() at the top of the method body and pass the module-method combination via $block_path:

<?php
class Reports extends Trongate {

  public function dashboard(): void {
    echo 'Public dashboard';
  }

  public function generate_pdf(): void {
    block_url('reports/generate_pdf');
    // PDF generation logic here
  }

}

The result:

• /reports/dashboard → ✓ Works
• /reports/generate_pdf → ✗ Returns 403 Forbidden
• $this->reports->generate_pdf() → ✓ Works from code

The method remains public and callable from other modules. Only direct URL invocation is blocked.

How It Works

When a request is made, block_url() inspects the supplied $block_path and compares it with the current URL segments.

In the above example, if a visitor attempts to access:

1. /reports/generate_pdf
2. The framework routes to Reports::generate_pdf()
3. block_url('reports/generate_pdf') executes
4. Segment 1 equals reports and segment 2 equals generate_pdf
5. A 403 Forbidden response is returned and execution stops

However, when the same method is called from code:

1. Code executes $this->reports->generate_pdf()
2. The current URL reflects whatever page the user is actually visiting
3. The segment comparison does not match
4. Execution continues normally

Blocking an Entire Module

Some modules should never be accessed via a browser. Examples include payment processors, email handlers, background services, and internal utility modules.

To block all methods in a module, pass only the module name to block_url() via $block_path. The most appropriate place to do this is inside the constructor.

<?php
class Payment extends Trongate {

  public function __construct(?string $module_name = null) {
    parent::__construct($module_name);
    block_url('payment');
  }

  public function process_charge(int $amount): void {
    // Payment logic
  }

  public function refund(string $transaction_id): void {
    // Refund logic
  }

}

The result:

• /payment/process_charge → ✗ Returns 403 Forbidden
• /payment/refund → ✗ Returns 403 Forbidden
• $this->payment->process_charge(100) → ✓ Works from code
• $this->payment->refund('txn_123') → ✓ Works from code

Form Validation Callbacks

Validation callbacks should always be protected to prevent direct browser access.

Use block_url() inside the callback and pass the appropriate module-method target via $block_path:

<?php
class Members extends Trongate {

  public function create(): void {
    $this->validation->set_rules('username', 'username', 'required|callback_username_check');

    if ($this->validation->run() === true) {
      // Create the member...
    }
  }

  public function username_check(string $str): string|bool {
    block_url('members/username_check');

    if ($str === '') {
      return true;
    }

    if (!preg_match('/^[a-zA-Z0-9_]+$/', $str)) {
      return 'The {label} can only contain letters, numbers, and underscores.';
    }

    $update_id = (int) segment(3);
    $is_available = $this->model->is_username_available($str, $update_id);

    if ($is_available === false) {
      return $update_id === 0
        ? 'The {label} is already taken. Please choose another.'
        : 'The {label} is already in use by another account.';
    }

    return true;
  }

}

This ensures the callback can only be executed by the validation engine and can never be triggered by visiting /members/username_check directly in a browser.

The Underscore-First Technique

Trongate v1 veterans will remember a simpler approach, and it remains fully supported in Trongate v2: prefix any method name with an underscore (_) and the framework will refuse to invoke it via the URL.

Any method whose name begins with an underscore can never be triggered by navigating to a URL. The framework intercepts the request before the controller is even loaded and returns a 404 Not Found response.

<?php
class Tax extends Trongate {

  public function index(): void {
    $total = $this->_calculate_tax(100);
    echo 'Total: ' . $total;
  }

  public function _calculate_tax(int $amount): int {
    return (int) round($amount * 1.2);
  }

}

The result:

• /tax/index → ✓ Works
• /tax/_calculate_tax → ✗ Returns 404 Not Found
• $this->_calculate_tax(100) → ✓ Works from code
• Modules::run('tax/_calculate_tax', [100]) → ✓ Works from code

How It Works

When a request arrives, the framework examines the second URL segment (the method name) before loading the controller file. If the segment begins with an underscore, the request is rejected immediately with a 404 Not Found response and execution stops. The method never loads and never runs.

Because enforcement happens at the routing stage - before the controller is instantiated and before its constructor runs - the protection is both automatic and earlier than block_url(), which only takes effect once the method body starts executing.

Where This Technique Genuinely Helps

The underscore-first technique carries a v1 heritage, but it isn't purely a migration convenience. It has three concrete properties that make it a defensible choice in new v2 code, not just old code:

• Earlier interception. The block happens at the routing stage, before the controller loads or its constructor executes. block_url(), by contrast, only runs once the method body begins - meaning the constructor has already completed. If a constructor does anything expensive or sensitive, this distinction can matter.
• Less information disclosure. A blocked underscore method returns 404 Not Found - indistinguishable, from the outside, from a URL that was never a route at all. block_url() returns 403 Forbidden, which confirms to anyone probing your URLs that the endpoint exists but is off-limits. If you'd rather not reveal your internal method surface to automated scanning, the 404 response leaks less.
• Zero boilerplate, nothing to misconfigure. block_url() requires you to type a matching path string correctly ('module/method') - get it wrong and the method is silently left unprotected. The underscore prefix can't be misconfigured in the same way: the name is the protection, and the router enforces it uniformly.

The trade-off is naming: the underscore becomes a permanent part of the method's name, and that cost is paid at every call site ($this->_calculate_tax(), Modules::run('tax/_calculate_tax')) for as long as the method exists. It's also a less immediately self-documenting signal than an explicit block_url() call - a reader unfamiliar with the convention may not recognise the underscore as a deliberate access-control decision.

PHP Method Visibility: The Simplest Guard

Since release 2.2026.0801, Trongate v2 blocks URL invocation of private and protected controller methods. The dispatcher reflects on the target method and, if it is not public, returns a clean 404 Not Found — exactly as if the page did not exist. (Before this release, such a request produced a PHP fatal error and a 500 response.)

<?php
class Tax extends Trongate {

  public function index(): void {
    $total = $this->calculate_tax(100);
    echo 'Total: ' . $total;
  }

  private function calculate_tax(int $amount): int {
    return (int) round($amount * 1.2);
  }

}

The result:

• /tax/index → ✓ Works
• /tax/calculate_tax → ✗ Returns 404 Not Found
• $this->calculate_tax(100) → ✓ Works from code (in-class call)

Choosing Between the Three Mechanisms

All three techniques stop direct URL invocation. They differ in when the block happens, what response the visitor sees, and what remains callable. The table below summarises the differences; the guidance above explains the reasoning behind each row.

As a starting point: reach for private/protected first if the method never needs to be called from outside its own class - it's the strictest guarantee with no guard code at all. If the method does need to stay callable from other modules, block_url() is the more explicit, self-documenting default. The underscore-first technique remains a legitimate choice alongside it - not merely a migration fallback - when its earlier interception, quieter 404 response, or zero-configuration guarantee matter for the method in question, or when you're bringing existing v1 conventions forward.