Routing Fundamentals

The skeleton of every application is routing. This page will introduce you to the fundamental concepts of routing for the web and how to handle routing in Prisma PHP.

Terminology

First, you will see these terms being used throughout the documentation. Here's a quick reference:

Routing Structure
  • Tree: A convention for visualizing a hierarchical structure. For example, a component tree with parent and children components, a folder structure, etc.
  • Subtree: Part of a tree, starting at a new root (first) and ending at the leaves (last).
  • Root: The first node in a tree or subtree, such as a root layout.
  • Leaf: Nodes in a subtree that have no children, such as the last segment in a URL path.
Routing Structure
  • URL Segment: Part of the URL path delimited by slashes.
  • URL Path: Part of the URL that comes after the domain (composed of segments).

The app Router

Prisma PHP by default uses a file-system based router where folders are used to define routes. Each folder represents a route segment that maps to a URL segment. To create a nested route, you can nest folders inside each other.

The App Router works in the directory named app. The app directory works as the root directory for the application.

App Root Router

Route Segments

Each folder in a route represents a route segment. Each route segment is mapped to a corresponding segment in a URL path.

Basic Routing

Nested Routes

To create a nested route, you can nest folders inside each other. For example, you can add a new /dashboard/settings route by nesting two new folders in the app directory.

The /dashboard/settings route is composed of three segments:

  • / (Root segment)
  • dashboard (Segment)
  • settings (Leaf segment)

File Conventions

Prisma PHP provides a set of special files to create UI with specific behavior in nested routes:

  • layout.php Shared UI for a segment and its children
  • index.php The default file that will be executed when a route is accessed. This file is used to make route segments publicly accessible.
  • not-found.php Not found UI for a segment and its children
  • loading.php Loading UI for a segment and its children
  • error.php Error UI for a segment and its children

Component Hierarchy

The Prisma PHP components defined in special files of a route segment are rendered in a specific hierarchy:

  • Root Layout: The layout.php file in the root segment is the root layout for the application.
  • Segment Layout: The layout.php file in a segment is the layout for the segment and its children.
  • Page: The index.php file in a segment is the page for the segment.
  • Not Found: The not-found.php file in the root segment is the not found UI for the application.

Colocation

Colocation is a practice of organizing files in a way that makes it easier to understand and maintain the application. In Prisma PHP, you can colocate files in the app directory to keep related files together.