☰
Trongate PHP Framework Docs
Introduction
Basic Concepts
Understanding Routing
Intercepting Requests
Module Fundamentals
Database Operations
Templates
Helpers
Form Handling
Form Validation
Working With Files
Image Manipulation
Working With Dates & Times
Language Control
Authorization & Authentication
Tips And Best Practices

Understanding Image Paths

Successfully working with images in Trongate requires understanding three distinct types of paths and when to use each one.

The Three Types of Paths

Every image in a Trongate application can be referenced using three different path formats:

Path Types Explained:

  • Relative path: Path relative to application root (e.g., public/images/logo.png or ../modules/shop/products/widget.jpg)
  • Absolute path: Complete filesystem path from root (e.g., /var/www/html/myapp/public/images/logo.png)
  • URL: Web-accessible address (e.g., https://example.com/images/logo.png or shop_module/products/widget.jpg)

Which Path Type to Use When

Understanding when to use each path type is essential:

The Image module methods operate on a loaded image resource in memory. Most operations don't take file paths at all - they work on the image already loaded via the method or the method.

For Image Module Operations

The Image module follows a three-step pattern:

  1. Upload/Load: Get the image into memory via upload() (for new uploads) or load() (for existing images)
  2. Process: Call methods like resize_to_width(), resize_to_height(), resize_and_crop()
  3. Save: Write the result using save()

Only upload(), load(), and save() deal with file paths. When they do, use relative paths:

Why Relative Paths Are Recommended:

Relative paths work consistently across development, staging, and production environments. Absolute paths break when you move your application to a different server or directory structure.

When to Use upload() vs. load():

  • upload(): Use for NEW images coming from user file uploads. Automatically handles validation, security checks, and optional resizing/thumbnails.
  • load(): Use for EXISTING images already stored on disk. Perfect for batch processing, generating new sizes, or creating thumbnails from stored images.

For Browser Display

When displaying images in HTML, use URLs:

The Module Asset Trigger

Images stored in module directories require special handling for browser display. Trongate uses a naming convention called the "module asset trigger":

The Module Asset Trigger Pattern:

To display images from a module, append _module to the module name in the URL:

  • Filesystem path (for PHP): ../modules/shop/products/widget.jpg
  • Browser URL (for HTML): shop_module/products/widget.jpg

Example: Converting Paths for Display

In the view:

Important: The _module trigger only works in browser URLs. It does not work with Image module methods that operate on the filesystem.

What You Get When Uploading Images

When you call , it returns an array with five pieces of information:

Understanding the Return Values:

  • file_name: Just the filename - useful for display or storage
  • file_path: Filesystem path - store this in your database
  • file_type: MIME type - useful for validation
  • file_size: Size in bytes - useful for display or quotas
  • thumbnail_path: Filesystem path to thumbnail - store this too

Notice that both file_path and thumbnail_path are filesystem paths, not URLs. You'll need to convert these when displaying images in your views.

Common Path Scenarios

Scenario 1: Public Directory Image

Scenario 2: Module Directory Image

Scenario 3: Loading and Processing Existing Images

Load vs. Upload: Use load() when working with images that already exist on your server. This is perfect for batch processing jobs, creating additional sizes from stored images, or building image galleries from existing files. Use upload() only for handling new file uploads from users.

Scenario 4: Processing Multiple Sizes from Database Path

Including a <base> tag in your page head ensures that all relative URLs - including module asset URLs such as shop_module/products/widget.jpg - resolve from the application root rather than the current request path.

This is especially important in Trongate applications, where pages are often rendered from nested routes or modules. Setting a base tag prevents broken images, scripts, and links when URLs are constructed relative to deeper paths.

Essential Guidelines

  • ✅ Use upload() for NEW images from user uploads
  • ✅ Use load() for EXISTING images already on disk
  • ✅ Use relative filesystem paths for Image module methods (load(), save())
  • ✅ Use URLs for browser display in HTML
  • ✅ Store filesystem paths in your database
  • ✅ Convert module paths to URLs using the _module trigger in views
  • ✅ Public directory images have simpler URL construction
  • ✅ The _module trigger only works in browser URLs, not PHP methods
  • ❌ Never use URLs with Image module processing methods
  • ❌ Never use filesystem paths in HTML image tags
  • ❌ Never use absolute paths unless absolutely necessary (they break portability)