DEV Community: Sami Maxhuni

Writing Clean, Flexible Query Filters in Laravel: Why I Built the QueryFilter Package

Sami Maxhuni — Sat, 26 Apr 2025 11:55:51 +0000

As a Laravel developer, I’ve always appreciated the elegance of Eloquent. But when it came to filtering complex queries especially when the filters depended on request parameters I found myself writing bloated controller logic or messy conditional clauses that just didn’t feel very “Laravel-ish.”

So I built QueryFilter a lightweight Laravel package designed to help you cleanly and fluently apply filters to your Eloquent queries, without sacrificing readability or flexibility.

Let me tell you the story behind it.

🧩 The Problem: Conditional Queries Get Messy Fast

If you’ve worked on real-world APIs, you’ve seen something like this:

$query = User::query();

if (request('name')) {
    $query->where('name', 'like', '%' . request('name') . '%');
}

if (request('email')) {
    $query->where('email', request('email'));
}

if (request('active')) {
    $query->where('is_active', true);
}

This starts out manageable but grows into a rat’s nest as your filters expand. Moving this logic to repositories or service classes helps only so much.

I wanted a way to:

Decouple request parameters from query logic
Make filters reusable and testable
Keep controller code clean and focused

💡 The Solution: A Modular Query Filtering Approach

Inspired by Laravel’s pipeline pattern and modular thinking, I built QueryFilter to let you define each filter as its own class, like so:

namespace App\Filters;

use Samushi\QueryFilter\Filter;
use Illuminate\Database\Eloquent\Builder;

class Search extends Filter
{
    /**
     * Search results using whereLike
     * 
     * @param Builder $builder
     * @return Builder
     */
    protected function applyFilter(Builder $builder): Builder
    {
        // Search with relationship: ['name', 'posts.title']
        return $builder->whereLike(['name'], $this->getValue());
    }
}

Then apply them like this:

User::queryFilter([
    Name::class,
    Email::class,
    Active::class,
])->get();

This approach achieves single responsibility, high readability, and full testability.

⚙️ Under the Hood

QueryFilter uses a pipeline to pass the query builder through each filter class. Each filter decides whether or not to act based on the request data (or any source you inject). You can even mock them in your tests or reuse them in multiple models.

By default, it works out of the box with Laravel’s container and request lifecycle — no complex setup needed.

✅ Use Cases

REST API filtering: Keep controllers clean while supporting many filters
Admin panels: Modular filters tied to inputs like search forms or toggles
Reusable filters: Create a library of filter classes to apply across models

🧪 Testing and Maintenance

Because each filter is just a class with logic, testing is trivial:

public function test_name_filter_applies_like_query()
{
    $query = User::query();

    $filter = new Name(['name' => 'John']);
    $filter->handle($query, fn($q) => $q);

    $this->assertStringContainsString('like', $query->toSql());
}

This also means you can refactor or extend individual filters without affecting the rest of the query pipeline.

📦 Open Source and Ready to Use

👉 Check it out on GitHub

👉 Contributions and feedback are welcome

👋 Final Thoughts

I didn’t build QueryFilter because Laravel lacked power — I built it to make my daily workflow cleaner and more expressive. As senior developers, we care not just about what works but how it works — and more importantly, how easy it is to maintain and scale.

If you’ve ever been frustrated by sprawling query logic, I hope this package brings the same relief it brought me.

Let me know what you think or how you’d improve it.

Bringing Laravel-style Named Routes and Dynamic Params to Next.js

Sami Maxhuni — Sat, 26 Apr 2025 11:44:08 +0000

When I first started working with Next.js, coming from years of experience with Laravel, I immediately missed one particular thing: named routes.

In Laravel, using named routes like route(‘dashboard.users.edit’, [‘id’ => 1]) was a dream. Clean, centralized, and safe. I never had to worry about writing URL strings manually or breaking links after a route changed.

But in Next.js, especially with the new App Router in Next 13+ (and now 15), this kind of system didn’t exist out of the box. You had to hardcode paths or rely on constants with plain strings, which felt messy and repetitive.

So I asked myself — why not bring Laravel’s route magic to Next.js?

This is how I built a custom route helper that gives me:

Centralized named route definitions
Support for nested and deeply nested routes
Dynamic parameter replacement (e.g., :id)
Full TypeScript support with autocomplete

Let’s dive in.

🧩 The Idea

We define all routes in a single object, grouped like in Laravel, and use a helper function to:

Get the full URL by route name
Replace any dynamic parameters

💡 Routes Definition (with nested groups and params)

// routes.ts
type Routes = {
  [key: string]: string | Routes;
};

function prefixRoutes(basePath: string, routes: Routes): Routes {
  const result: Routes = {};

  for (const key in routes) {
    const value = routes[key];
    if (typeof value === 'string') {
      result[key] = basePath + (value === '/' ? '' : value);
    } else {
      result[key] = prefixRoutes(
        basePath + (key.startsWith('/') ? '' : '/' + key),
        value
      );
    }
  }

  return result;
}

export const prefixedRoutes = {
  dashboard: prefixRoutes('/dashboard', {
    home: '/',
    users: {
      edit: '/users/:id/edit',
    },
    test: {
      test1: {
        something: '/test1/:somethingId/something',
      },
    },
  }),
} as const;

This gives us route names like:

dashboard.home ➜ /dashboard
dashboard.users.edit ➜ /dashboard/users/:id/edit
dashboard.test.test1.something ➜ /dashboard/test/test1/:somethingId/something

🧠 Route Helper Function

This function takes a route name like ‘dashboard.users.edit’ and optional parameters { id: 123 }, returning the final URL.

// route.ts
import { prefixedRoutes } from './routes';

export function route(name: string, params?: Record<string, string | number>): string {
  const parts = name.split('.');

  let current: unknown = prefixedRoutes;
  for (const part of parts) {
    if (current && typeof current === 'object' && part in current) {
      current = (current as Record<string, unknown>)[part];
    } else {
      return '/';
    }
  }

  if (typeof current !== 'string') return '/';

  let url = current as string;

  if (params) {
    for (const key in params) {
      url = url.replace(`:${key}`, String(params[key]));
    }
  }

  return url;
}

✅ Usage Examples

import { route } from './route';

// 1. Simple route
const homeUrl = route('dashboard.home'); 
// → /dashboard

// 2. With dynamic param
const editUserUrl = route('dashboard.users.edit', { id: 123 }); 
// → /dashboard/users/123/edit

// 3. Deeply nested
const somethingUrl = route('dashboard.test.test1.something', { somethingId: 42 });
// → /dashboard/test/test1/42/something

You can use this route helper in router.push, Link, or href anywhere in your Next.js app.

<Link href={route('dashboard.users.edit', { id: user.id })}>
  Edit User
</Link>

🧪 Type Safety and Improvements

This is just the beginning. You can expand it with:

Stronger TypeScript typings (e.g. typed route names)
Compile-time checks for missing params
Query string support (route(‘dashboard.users.edit’, { id: 1, tab: ‘profile’}))

🎯 Final Thoughts

This small system brought back all the joy and safety I had with Laravel routing, right into my Next.js project. No more hardcoded strings, no more guesswork.

If you’re working in a larger app with nested dashboards, user management, or any modular structure I highly recommend this approach. It’s simple, elegant, and familiar for Laravel developers.