File based routing

In WebEngine, routes are file-based. That means the URL is not usually defined in a central routing table. Instead, it maps directly to files and directories in the project.

This keeps routing obvious. If we know the URL, we can usually guess where the view and logic files live. If we know the file path, we can usually guess the URL.

How Paths Resolve

The root URL / maps to page/index.html. A nested URL such as /about/team maps to page/about/team.html.

Directory-style URLs are also supported. That means a path can resolve through an index file inside a directory. For example:

• / -> page/index.html
• /blog -> page/blog.html or page/blog/index.html
• /blog/post -> page/blog/post.html

It is best to avoid creating clashing paths such as both page/contact.html and page/contact/index.html, because that makes the route less obvious to the next developer reading the project.

HTML and PHP Pairing

Each route can have an HTML view file, a PHP logic file, or both. In the normal case:

• page/about.html is the page view
• page/about.php is the page logic

If only the HTML file exists, the page is static and can still be served perfectly well. If only the PHP file exists, there is no page view to render and the route is incomplete. WebEngine expects a view for a page response.

This pairing is one of the main shapes to get comfortable with. It lets the response be built from ordinary HTML first, with PHP added only when the page actually needs behaviour.

Keep code obvious

This model makes code navigation fast because there are fewer places to look. There is no need to search through a routing table before we can even find the page.

It also keeps more advanced features straightforward. Dynamic routes, shared headers and footers, components, and partials all build on top of the same idea that a path on the web should map cleanly to a path in the project.

---

Let's learn about HTML in page views, then we'll cover PHP in page logic.