Prisma PHP Logo

URL State Manager

Stop treating the URL as a static string. With searchParams, your URL query parameters become a reactive data store. Update filters, tabs, and search queries instantly while keeping the browser history clean.

Shareable UI

Users can copy the URL and send it to a friend, who will see the exact same filters and active tabs.

History Support

Updates automatically push to browser history, making the Back Button work as expected.

Reactive Listeners

Register callbacks to trigger JavaScript logic whenever the URL changes (even via browser controls).

Real World: Search & Filter

This example shows the "Golden Circle" of URL state: PHP reads it on load, HTML displays it, and JavaScript updates it while typing.

Try the concept:
Learn about Request →
Deep dive into Request::$params and more.
Search Implementation 
<?php
use PP\Request;

// 1. Retrieve value from URL (e.g., ?q=hello)
$searchValue = Request::$params->q ?? '';
?>

<!-- 2. Initialize input with current value -->
<input
    type="text"
    value="<?= $searchValue ?>"
    oninput="getSearchParams(event.target.value)"
    placeholder="Search..."
    class="input" 
/>

<script>
    // 3. Bind Input to URL Reactively
    function getSearchParams(val) {
        if (val) {
            // Adds ?q=value to URL & pushes history
            searchParams.set('q', val);
        } else {
            // Clean URL if empty
            searchParams.delete('q');
        }
    }
</script>

Listening for Changes

Listener Logic 
// Triggered by searchParams.set() OR Back/Forward buttons
searchParams.listen((params) => {
    
    const currentTab = params.get('tab');
    
    if (currentTab === 'reviews') {
        showReviewsSection();
    } else {
        showDetailsSection();
    }

    console.log("URL Changed!", params.toString());
});

The listen method is crucial for Single Page Application (SPA) behavior.

Why use this?

If a user updates the URL manually or presses the browser's Back button, standard variables won't know. searchParams.listen hooks into the window's popstate event to ensure your UI stays in sync with the URL bar at all times.

API Reference

Method / Property Signature Description
searchParams.get (key: string): string|null Retrieves the first value associated with the given search parameter.
searchParams.set (key: string, val: string) Sets the value associated with a given search parameter and pushes a new history entry.
searchParams.delete (key: string) Deletes the given search parameter and its associated value from the list.
searchParams.replace (params: Object) Bulk update. Uses replaceState (does not create new history entry). Useful for cleanup.
searchParams.listen (cb: (params) => void) Registers a callback function that runs whenever the URL query parameters change.