Appearance

Limitations ​

Because static websites generate HTML files ahead of time, some request-specific features are not available at runtime, such as query parameters, sessions, POST forms, or authentication. Ozu mitigates these constraints by providing patterns that keep your code as close as possible to a classic Laravel application.

Query string ​

Let’s consider a common use case: displaying a sortable list of projects. In a typical Laravel application, you would define a route like this:

php
Route::get('/projects')

In the controller, you would then read a query parameter to determine the sort order, for example: /projects?sort=asc.

In an Ozu project—as with any static website—you cannot dynamically read query parameters in the controller, since the HTML files are generated at build time. As a result, the sorting logic cannot rely on the query string on the backend.

To handle this limitation, you can use one of the following approaches:

Move the query to a path parameter ​

For example: /projects/list/{sort} This will generate one static HTML file per variant, such as:

  • projects/list/asc.html
  • projects/list/desc.html

Handle the query string on the frontend ​

Use client-side JavaScript (for example with Alpine.js) to read and react to the query string dynamically after the page has loaded.

Both approaches allow you to preserve sorting functionality while remaining compatible with static generation.

Pagination ​

For the same reason, query-based pagination (e.g. ?page=1) cannot work with statically generated HTML. Instead, the page number must be included as a path segment:

php
Route::get('/projects/index/{page}')

Ozu takes care of this internally by overriding Laravel’s default paginator. You can still use familiar helpers such as {{ $projects->links() }} or route('projects.index', ['page' => 2]): the paginator will automatically generate URLs using path segments instead of query parameters, while keeping your pagination logic unchanged.

Sessions ​

By definition, sessions are not available on statically generated websites, since there is no server-side request lifecycle. If you need to persist user-specific data, you can rely on client-side storage mechanisms such as:

  • cookies
  • localStorage (via JavaScript)

Forms ​

Because static sites cannot process form submissions on the backend, forms must be handled by an external service.

At the current stage of Ozu, you’ll need to rely on a third-party provider to manage form submissions. Many solutions are available, such as FieldGoal.