File based routing

In WebEngine, routes are file-based. That means the requested URI directly maps to project files, instead of having a central routing table. This keeps routing obvious and predictable. If we know the URI, 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

Those two forms are alternatives, not companions. If a project contains both page/contact.html and page/contact/index.html for the same route, WebEngine treats that as an ambiguous path and throws an exception rather than guessing which file should win.

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, describing the page's layout and structure
• page/about.php is the page logic, defining the page's behaviour and adding dynamic content

If only the HTML file exists, the page is static and will be served without change. 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 dynamic 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 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.

There are tools for keeping page files tidy as they grow: Custom HTML components for splitting HTML tags into their own reusable files, and Page partials for defining reusable templates.

---

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