Routing

Introduction

All requests to your application are handled by Laravel unless you create the routes using one of the specific methods described below.

Defining Routes

The Streams platform has a couple of ways it routes requests, which are listed below. Otherwise, standard Laravel routing applies.

Route Files

You can configure routes just as you would in a regular Laravel application using the routes/web.php file.

Streams Router

The Streams platform provides a Route::streams() method for defining routes. All streams-specific routing approaches pass through this method.

// Options
Route::streams('uri', [
    'foo' => 'bar',
]);

// View
Route::streams('uri', 'view');

// Controller
Route::streams('uri', 'App\Http\Controller\Example@show');

// Controller and more
Route::streams('uri', [
    'uses' => 'App\Http\Controller\Example@show'
]);

The first argument is the URI and the second is either:

• The name of the view to render.
• A callable string.
• An array of route options.

Stream Routes

Defining routes in your stream configuration makes it easy to automate naming and URL generation around your domain information and entities.

Define stream routes using a action => options format, where options is again either the URI, controller and method string, or an array of route options.

In streams/contacts.json:

{
    "routes": {
        "index": {
            "uri": "contacts",
            "view": "contacts"
        },
        "view": {
            "uri": "contacts/{id}",
            "view": "contact"
        },
        "profile": {
            "uri": "contacts/{id}",
            "view": "profile"
        }
    }
}

Automatic Naming

Unless a route name is specified, stream configured routes automatically name themselves like streams::{stream}.{action}.

$url = route('streams::contacts.index');

Automatically Resolved Views

Unless a view is specified, the associated requests will attempt to resolve a view automatically.

In streams/contacts.json:

{
    "routes": {
        "index": {
            "uri": "contacts"
        },
        "view": {
            "uri": "contacts/{id}"
        }
    }
}

EntryController picks the first view that exists, in this order:

1. The route's view option.
2. A view with the same name as the route (as).
3. For a route that resolves an entry (contacts/{id}), the singular stream ID (resources/views/contact.blade.php). Otherwise, the plural (resources/views/contacts.blade.php).

If none exists, no view is set.

Route Parameters

The Streams platform adds support for deep parameter variables using a dot notation when using the URL::streams() method to generate URLs.

URL::streams('uri/{foo.bar}', 'view');

Stream Parameter

You can specify the stream associated with the route using the route option or by using the {stream} URI segment variable in your URI pattern to resolve the stream by its handle.

Route::streams('address-book/{stream}', 'contacts');

Consider locking down this routing pattern using a parameter constraint.

Route::streams('address-book/{stream}', [
    'view' => 'contacts.list',
    'constraints' => [
        'stream' =>  '(businesses|family)'
    ],
]);

The resolved stream will be available within the view:

@verbatim<h1>{{ $stream->name }}</h1>

<ul>
    @foreach ($stream->entries()->get() as $entry)
    <li>{{ $entry->name }}</li>
    @endforeach
</ul>@endverbatim

Entry Parameters

You can specify a stream entry associated with the route using the route option or by using the {id} URI segment variable in your URI pattern to resolve the entry by its ID or handle.

Route::streams('address-book/{stream}/{id}', 'contacts');

You can also use {entry.*} parameters to query the entry by its field values.

// address-book/contacts/[email protected]
Route::streams('address-book/{stream}/{entry.email}', 'contacts');

The first matching entry will be available within the view:

@verbatim<h1>{{ $entry->name }}</h1>@endverbatim

A 404 error page will be displayed entry resolution is attempted, but no entry is found.

Route Options

All Streams platform-specific methods of registering routes support the following route options.

All route options are parsed with controller data:

Route::streams('address-book/{stream}/{id}', [
    'view' => '{streams.handle}',
]);

View

Use the view option to specify a view to render:

Route::streams('uri', [
    'foo' => 'bar',
    'view' => 'example',
]);

Stream

Use the stream option to specify the stream associated with the request. Stream configured routes will do this automatically.

Route::streams('uri', [
    'stream' => 'contacts',
]);

The stream is automatically injected into the view:

@verbatim<h1>{{ $stream->name }}</h1>

<ul>
    @foreach ($stream->entries()->get() as $entry)
    <li>{{ $entry->name }}</li>
    @endforeach
</ul>@endverbatim

Entry

You can also specify a specific entry identifier:

Route::streams('uri', [
    'stream' => 'contacts',
    'entry' => 'john_smith',
]);

The stream entry is automatically injected into the view:

// uri/ryan_thompson
@verbatim<h1>{{ $entry->name }}</h1>@endverbatim

You can use entry fields to query entries for the view.

// uri/[email protected]
Route::streams('uri/{entry.email}', [
    'stream' => 'contacts',
]);

You can also hard code the entry ID or handle:

Route::streams('uri', [
    'stream' => 'contacts',
    'entry' => 'ryan_thompson',
]);

The first result is automatically injected into the view:

// uri/ryan_thompson
@verbatim<h1>{{ $entry->name }}</h1>@endverbatim

Redirect

Use the redirect and optional status_code option to specify a redirect:

Route::streams('uri/{entry.name}', [
    'redirect' => '/new/uri',
    'status_code' => 301, // Default
]);

Redirects highlight a good use case to leverage the fact that route options are parsed with controller data:

Route::streams('uri/{entry.name}', [
    'redirect' => '/new/uri/{stream.id}/{entry.name}',
    'status_code' => 301, // Default
]);

Native Redirects

You can create Laravel redirects in your routes/web.php using the Route facade as well:

Route::redirect('/from', '/to');
Route::redirect('/from', '/to', 301);
Route::permanentRedirect('/from', '/to');

Named Routes

Use the as option to specify the name of the route:

Route::streams('uri', [
    'view' => 'example',
    'as' => 'login',
]);

You can refer to the route by name using the typical Laravel methods:

$url = route('login');

HTTP Verbs

Use the verb option to specify the HTTP verb the route should respond to:

Route::streams('uri', ['verb' => 'any']);
Route::streams('uri', ['verb' => 'get']); // Default
Route::streams('uri', ['verb' => 'put']);
Route::streams('uri', ['verb' => 'post']);
Route::streams('uri', ['verb' => 'patch']);
Route::streams('uri', ['verb' => 'delete']);
Route::streams('uri', ['verb' => 'options']);

Route Middleware

Use the middleware option to assign additional middleware to the route:

Route::streams('uri', [
    'middleware' => ['first', 'second']
]);

Parameter Constraints

Use the constraints option to specify allowed parameter formatting for the route using regular expression:

Route::streams('uri/{name}', [
    'constraints' => ['name' => '[A-Za-z]+']
]);

Laravel does not support dots in parameter names at this time. For this reason, {entry.name} type parameters transform into {entry__name}.

Route::streams('uri/{entry.name}', [
    'constraints' => ['entry__name' => '[A-Za-z]+']
]);

Disabling CSRF

You can disable CSRF protection using the csrf option.

Route::streams('uri', [
    'csrf' => false
]);

Deferring Routes

Use the defer option to defer registering a route.

Route::streams('/{id}', [
    // ...
    'defer' => true,
]);

Generating URLs

You may use the URL::streams() method to generate URLs for named routes, including those with dotted parameter variables. This method also supports parsing URL strings with parameter data. The extra data argument is appending as a query string. Use the absolute argument to control whether the resulting URL is absolute or not.

URL::streams($target, $parameters = [], $extra = [], $absolute = true);

$entry = Streams::entries('contacts')->first();

// contacts/{entry.email}/{entry.id}
$url = URL::streams('streams::contacts.view', ['entry' => $entry]);

// contacts/{email}/{id}
$url = URL::streams('streams::contacts.view', $entry);

You can also use Laravel URL generation for named routes, though dotted parameters are not supported using Laravel methods:

// Generating URLs.
$url = route('streams::contacts.index');

// Generating Redirects.
return redirect()->route('streams::contacts.index');

Error Pages

Errors render views based on the status code of the error. For example, a 404 error will look a view in resources/views/errors/{status_code}.blade.php.

Laravel will automatically render a 404 page for any unhandled routes.

• Laravel Custom Error Pages