PHPackages                             miranj/craft-router - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. miranj/craft-router

ActiveCraft-plugin[Utility & Helpers](/categories/utility)

miranj/craft-router
===================

Use URL segments as filtering criteria on an entry query.

1.7.0(5mo ago)231.6k↑66.7%MITPHPPHP ^7.2.5 || ^8.0

Since Jun 5Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/miranj/craft-router)[ Packagist](https://packagist.org/packages/miranj/craft-router)[ RSS](/packages/miranj-craft-router/feed)WikiDiscussions v1 Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (16)Used By (0)

[![Router icon](./src/icon.svg)](./src/icon.svg)

Router
======

[](#router)

A [Craft CMS](https://craftcms.com/) plugin for using URL segments as filtering criteria on an entry query.

Contents
--------

[](#contents)

- [Why](#why)
    - [Demo](#demo)
- [Usage](#usage)
    - [Example](#example)
    - [Parameters](#parameters)
    - [Filters](#filter-types)
- [Installation](#installation)
- [Requirements](#requirements)
- [Changelog](./CHANGELOG.md)
- [License](./LICENSE)

Why
---

[](#why)

Craft makes it straightforward to declare [dynamic routes as regular expressions](https://craftcms.com/docs/5.x/system/routing.html#advanced-routing-with-url-rules "Advanced Routing with URL Rules - Craft CMS Documentation")and redirect them to be handled by a template. However, the templates themselves remain dumb handlers. They may optionally be passed on some context in the form of [named parameters](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing#named-parameters "Handling Requests: Routing and URL Creation | Yii 2.0") but they have to do the heavy lifting of building the data set required for rendering the page.

This may not be a problem for pages with one or two variables, like a blog's *year* and *month* archives (e.g. `blog/2015/01`). The template would fetch the list of posts from `craft.entries` and narrow the range depending on if the `year` and `month` variables are set.

But what if the blog also added a category page (e.g. `blog/camping`)? And what if the category pages supported their own yearly and monthly archive pages (e.g. `blog/camping/2014`)? We would either end up duplicating the code to fetch posts by creating multiple copies of the archive template, or end up adding the logic to handle category, year, and month *filters* all in a single template and increasing its overall complexity.

The Router plugin attempts to solve this problem by taking on the job of filtering entries based on URL parameters. It adds a new template variable `entries` which can be configured to, for the URL `blog/2015/01` contain blog posts published in January 2015, or for the URL `blog/camping/2014` to show blog posts published in 2014 under the category "Camping".

### Demo

[](#demo)

[![Custom Routing with Router, Craft The Planet](./demo-poster.jpg)](https://www.youtube.com/watch?v=ofv67KahW_M)

We recorded [a video (36 mins) about the plugin](https://www.youtube.com/watch?v=ofv67KahW_M) for Straight Up Craft. It talks about the problems that Router is trying to solve and includes a step-by-step tutorial + demo about using the plugin on the [Craft Blog Starter project](https://github.com/craftcms/starter-blog).

Usage
-----

[](#usage)

In order to create URL rules that automatically build an [Entry Query](https://craftcms.com/docs/5.x/reference/element-types/entries.html#querying-entries) based on the URL, you will need to create a `router.php` file in your config folder, adjacent to your existing `routes.php` file. The config file supports a single option `rules`, which should be set to an array containing the URL rules.

For [multi-site Craft setups](https://craftcms.com/docs/5.x/system/sites.html), you can define site-specific URL rules by placing them in a sub-array, with the key set to the site’s handle.

### Example

[](#example)

```