If you’ve found an error, spotted something missing, or feel a section could be clearer or better explained, we’d love to hear from you. Your feedback helps keep the documentation accurate and useful for everyone.
Please report issues or suggest improvements on GitHub. Community input is invaluable in making the docs stronger.
Not comfortable with GitHub? No problem — you can also get in touch with us directly via our contact form. We welcome all feedback.
Custom Routing: An Introduction
Custom routing allows you to create clean, intuitive URLs by mapping your desired URL patterns to specific controllers and methods. This feature is particularly useful for creating SEO-friendly URLs and intuitive navigation paths.
Configuration File
In Trongate, custom routes are defined within 'custom_routing.php'. This file is located in:
From a PHP/framework perspective, custom_routing.php does the following two things:
- Defines a PHP array named
$routes. - Assigns the value of
$routesto a PHP constant namedCUSTOM_ROUTES.
In normal usage, you (as the developer) will not need to reference the $routes array or CUSTOM_ROUTES directly after 'custom_routing.php' has been properly set up and saved.
Here is an example of PHP code you might typically find in custom_routing.php:
An Overview Of How Custom Routing Rules Are Defined
In Trongate, the $routes array maps incoming HTTP requests to code. Each item within the array is a key-value pair that defines a custom routing rule.
The key (i.e., the left side) for each rule is the desired URL pattern you want to match.
The value (i.e., the right side) defines what should be served when someone visits a URL that matches the left side.
Consider the following line of code from the example above:
Here, we are effectively telling Trongate:
"If someone visits shop, please behave as though they had just visited store/products."
Assume the base URL is defined like this:
In Trongate, the BASE_URL is defined in 'config.php'. Here is the file location:
In this case, a user who navigates to:
...would receive the same response from the website as if they had navigated to:
THIS IS REALLY IMPORTANT
All of the leading PHP frameworks have some kind of custom routing functionality.
Unfortunately, some developers appear to find the general topic of custom URL routing to be challenging. The main difficulty often comes from confusion about how custom URL routing differs from concepts like URL rewriting.
Let's clarify the topic at hand.
Don't confuse custom routing with URL rewriting or URL redirecting!
Custom routing determines what content gets served when a user visits a given URL. Custom routing does not change the actual URL that appears in the browser's address bar.
Custom Routing vs. URL Rewriting:
Custom Routing
- In PHP frameworks like Trongate, custom routing maps incoming requests (URLs) to specific controllers or actions without altering the visible URL.
- URL rewriting, often handled by the server (e.g., Apache's
.htaccessor Nginx rules), changes how URLs are processed internally by the server, sometimes hiding implementation details.
Redirecting
- Redirecting sends an HTTP response (e.g., 301, 302) to instruct the browser to navigate to a different URL. This does visibly change the address bar.
In Summary
Custom routing determines what content gets served when a user visits a given URL. It does not change the actual URL in the browser's address bar.
With Trongate, custom routing is handled via the file 'custom_routing.php'.
Custom routing rules are established by creating a $routes array, where each item is a key-value pair:
- The keys represent desired URL paths.
- The values represent what should be served.
Now, let's learn about custom routing patterns...