Educational

Dynamic Parameters in Routes in Phalcon

—

by

Saim Khalid
in

Routing is one of the most important components of any modern web framework. It determines how a URL request is processed and which controller action responds to it. In Phalcon—a framework known for its unmatched performance and low-level C-optimized execution—the routing system is both powerful and extremely flexible. One of its most useful features is dynamic parameters in routes, which gives developers the ability to capture variable values directly from the URL and pass them automatically to controllers.

Whether you are building user profiles, product pages, category listings, or blog articles, dynamic routing keeps URLs clean, SEO-friendly, and efficient. This guide explores everything you need to know about dynamic parameters in Phalcon routes: how they work, why they matter, how to implement them, best practices, and real-world examples.

Let’s dive in.

1. Introduction to Routing in Phalcon

Routing is the process of matching incoming requests to controller actions. In Phalcon’s MVC architecture, requests typically follow this structure:

/controller/action/parameters

However, Phalcon allows highly flexible routing rules, enabling custom, clean, expressive URL patterns.

1.1 Basic Routing Example

$router->add(

'/products',
[
    'controller' => 'products',
    'action'     => 'index',
]
);

This simple route maps /products to the ProductsController::indexAction() method.

But modern applications rarely use static URLs only. This is where dynamic parameters come in.

2. What Are Dynamic Parameters in Routes?

Dynamic parameters allow parts of the URL to be treated as variables instead of static text.

Example URL:

/product/42

Here, 42 is a dynamic value—usually the product ID.

With dynamic routing, Phalcon extracts the value and passes it automatically to the controller action:

public function viewAction($id)
{

echo $id; // Output: 42
}

2.1 Why Do We Need Dynamic Routes?

Dynamic parameters are essential when your content changes based on the URL:

  • Product detail pages
  • Blog article pages
  • Category listings
  • User profiles
  • Order details
  • Comments, posts, or messages

Dynamic routes help you build:

  • SEO-friendly URLs
  • Clean and readable routing rules
  • Flexible, scalable applications

3. How Phalcon Handles Dynamic Parameters

Phalcon uses a pattern syntax in routes to define dynamic parameters. It allows you to use placeholders that capture data automatically.

3.1 Basic Dynamic Routing Syntax

$router->add(

'/product/{id}',
[
    'controller' => 'product',
    'action'     => 'view',
]
);

Here:

  • {id} becomes a dynamic parameter
  • It gets passed to viewAction($id) in the controller

4. Types of Dynamic Parameters in Phalcon

Phalcon supports several types of dynamic parameters:

  1. Named parameters
  2. Regular expression parameters
  3. Optional parameters
  4. Wildcard parameters
  5. Multiple parameters in a single route

Each type provides different flexibility.

5. Using Named Dynamic Parameters

Named parameters are the simplest and most readable approach.

Example

$router->add(

'/user/{username}',
[
    'controller' => 'user',
    'action'     => 'profile',
]
);

URL:

/user/john-doe

Controller action:

public function profileAction($username)
{

echo $username; // john-doe
}

Named parameters simplify logic and keep code clean.

6. Using Regular Expressions in Dynamic Routes

Phalcon allows validation with regex patterns:

$router->add(

'/product/{id:[0-9]+}',
[
    'controller' => 'product',
    'action'     => 'details',
]
);

Meaning:

  • Only numbers allowed
  • /product/abc will NOT match
  • /product/42 will match

Controller:

public function detailsAction($id)
{

echo $id;
}

7. Optional Dynamic Parameters

You can make dynamic parameters optional:

$router->add(

'/blog/{year}/{month}/{day}',
[
    'controller' => 'blog',
    'action'     => 'archive',
]
);

You can also make some optional:

$router->add(

'/blog/{year}/{month}/{day}',
[
    'controller' => 'blog',
    'action'     => 'archive',
    'year'       => 0,
    'month'      => 0,
    'day'        => 0,
]
);

Controller:

public function archiveAction($year = 0, $month = 0, $day = 0)
{

// All parameters optional
}

8. Multiple Dynamic Parameters in One Route

You can capture several parameters in one route:

$router->add(

'/category/{slug}/{page:[0-9]+}',
[
    'controller' => 'category',
    'action'     => 'list',
]
);

URL:

/category/electronics/3

Controller:

public function listAction($slug, $page)
{

echo "Category: $slug, Page: $page";
}

9. Wildcard Dynamic Parameters

Wildcard dynamic routes capture everything after a point:

$router->add(

'/download/{file:.+}',
[
    'controller' => 'files',
    'action'     => 'download',
]
);

URL:

/download/path/to/file.zip

Controller:

public function downloadAction($file)
{

echo $file; // path/to/file.zip
}

10. Query Strings vs Dynamic Routes

Dynamic routes work with clean URLs:

/user/23

Instead of query strings:

user.php?id=23

Dynamic routes are better because:

  • Cleaner
  • Easier to memorize
  • SEO-friendly
  • More professional

11. How Dynamic Parameters Map to Controller Actions

When defining:

$id = 42;

Phalcon passes this directly to:

public function viewAction($id)

Automatic Mapping Rules

  • Parameter name in route → Parameter in method
  • Order does not matter if names match
  • Types can be controlled with regex

12. Using Default Parameter Values

You can define defaults:

$router->add(

'/product/{id}',
[
    'controller' => 'product',
    'action'     => 'view',
    'id'         => 1,
]
);

If no ID is provided, ID becomes 1.

13. Dynamic Parameters and Dependency Injection (DI)

Controllers receive parameters through routing, but everything else comes from DI, such as:

  • $this->db
  • $this->request
  • $this->response
  • $this->view

Dynamic parameters simply complement DI by providing per-request variables.

Example combined usage:

public function viewAction($id)
{

$product = $this->db->fetchOne(
    "SELECT * FROM products WHERE id = ?",
    \Phalcon\Db\Enum::FETCH_ASSOC,
    [$id]
);


$this->view->product = $product;
}

14. SEO Benefits of Dynamic Routing

Dynamic parameters help produce SEO-friendly URLs.

Examples

SEO-friendly:

/product/red-shoes

Not SEO-friendly:

product.php?id=343

Google prefers clean URLs.

15. Dynamic Parameters in REST APIs

Dynamic parameters are essential in API routes:

$router->add(

'/api/users/{id}',
[
    'controller' => 'apiUsers',
    'action'     => 'show',
]
);

Controller:

public function showAction($id)
{

$this->view->disable();
return $this->response->setJsonContent([
    'id' => $id
]);
}

16. Route Constraints and Validation

Using regex ensures proper format.

Examples:

  • Only letters: {slug:[a-zA-Z]+}
  • UUID format: {id:[0-9a-fA-F\-]{36}}
  • Hexadecimal: {color:[0-9a-fA-F]+}

17. Generating URLs with Dynamic Parameters

Phalcon allows URL creation:

echo $this->url->get(

'product/view/42'
);

Or using named routes:

$router->add(

'/product/{id}',
[
    'controller' => 'product',
    'action'     => 'view',
]
)->setName('product-view');

echo $this->url->get(

[
    'for' => 'product-view',
    'id'  => 42,
]
);

18. Testing Dynamic Routes

Use:

$router->handle('/product/55');
print_r($router->getParams());

19. Common Mistakes with Dynamic Parameters

  • Forgetting regex validation
  • Confusing parameter names
  • Not matching route parameter names with controller arguments
  • Too many wildcard routes
  • Overly complicated routing rules

20. Best Practices for Dynamic Routing

20.1 Keep Routes Clean

Use readable patterns.

20.2 Use Regex for Validation

Prevent invalid URLs.

20.3 Keep Controller Methods Slim

Don’t overload route handlers.

20.4 Use Named Routes

Helps generate URLs.

20.5 Avoid Duplicate Routes

Prioritize the most specific route.

21. Real-World Example: E-Commerce Product Routing

Route:

$router->add(

'/product/{slug}',
[
    'controller' => 'product',
    'action'     => 'details',
]
);

Controller:

public function detailsAction($slug)
{

$product = Products::findFirstBySlug($slug);
$this->view->product = $product;
}

View:

<h1>{{ product.name }}</h1>
<p>{{ product.description }}</p>

22. Real-World Example: Blog Category Routing

Route:

$router->add(

'/blog/{category}/{page:&#91;0-9]+}',
&#91;
    'controller' =&gt; 'blog',
    'action'     =&gt; 'category',
]
);

Controller:

public function categoryAction($category, $page)
{

$this-&gt;view-&gt;posts = Posts::findByCategory($category, $page);
}

23. Real-World Example: User Profiles

$router->add(

'/user/{username}',
&#91;
    'controller' =&gt; 'user',
    'action'     =&gt; 'profile',
]
);

Controller:

public function profileAction($username)
{

$this-&gt;view-&gt;user = Users::findFirstByUsername($username);
}

24. Handling Missing Parameters

Use default values:

public function viewAction($id = null)
{

if (!$id) {
    return $this-&gt;response-&gt;redirect('not-found');
}
}

25. Dynamic Parameters in Modular Apps

Modules allow more complex routing:

/admin/user/edit/5

26. Optimizing Dynamic Routes for Performance

Phalcon routing is fast, but still:

  • Limit number of wildcard routes
  • Use regex sparingly
  • Cache routes when possible

27. When NOT to Use Dynamic Routes

Avoid dynamic parameters when:

  • The URL never changes
  • The resource is always static
  • You need to protect sensitive IDs

28. Combining Dynamic Parameters with Query Strings

Both can be used together:

/products/12?page=3

29. Future-Proof Routing Strategy

Plan URLs early to avoid breaking changes.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *