Filtros del Query Builder

Introducción a los Filtros

El sistema de filtros de Laravel RoutingKit utiliza un patrón Query Builder que permite encadenar múltiples filtros antes de obtener los resultados finales. Todos los filtros se aplican sobre la instancia singleton del orquestador.

Iniciando una Nueva Consulta

Antes de aplicar cualquier filtro, debes iniciar una nueva consulta:

$query = rk_navigation()->newQuery();

Nota importante: El método newQuery() reinicia todos los filtros anteriores y proporciona un estado limpio para la nueva cadena de consulta.

Tabla de Métodos de Filtros

Método	Propósito	Parámetros
`loadContexts()`	Carga contextos específicos	`string\|array $contextKeys`
`loadAllContexts()`	Carga todos los contextos disponibles	-
`excludeContexts()`	Excluye contextos específicos	`string\|array $contextKeys`
`resetContexts()`	Reinicia contextos al estado por defecto	-
`withDepth()`	Filtra por nivel de profundidad máximo	`int\|null $level`
`filterByDepth()`	Alias de withDepth	`int\|null $level`
`forUser()`	Filtra para un usuario específico	`string\|null $userId`
`prepareForUser()`	Prepara filtro para usuario autenticado	`string\|null $userId`
`filterForCurrentUser()`	Filtra para el usuario actual	-
`filterForPermissions()`	Filtra por permisos	`array\|Collection $permissions`
`filterForRoles()`	Filtra por roles	`Collection $roles`
`filterOnlyFiles()`	Muestra solo archivos de contextos específicos	`string\|array $contextKeys`
`filterAllFiles()`	Muestra todos los archivos de todos los contextos	-
`withEmptyGroups()`	Incluye grupos vacíos en resultados	`bool $value = true`
`resetFilters()`	Reinicia todos los filtros aplicados	-

Agrupación de Filtros por Categorías

1. Filtros de Contexto

Los filtros de contexto controlan qué conjuntos de navegación se cargan:

// Cargar contextos específicos
$query = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard', 'footerDashboard']);

// Cargar todos los contextos
$query = rk_navigation()
    ->newQuery()
    ->loadAllContexts();

// Excluir contextos específicos
$query = rk_navigation()
    ->newQuery()
    ->loadAllContexts()
    ->excludeContexts(['adminPanel']);

2. Filtros de Permisos y Roles

Estos filtros controlan el acceso basado en permisos del usuario:

// Filtrar por permisos específicos
$permissions = ['dashboard.view', 'users.edit'];
$query = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard'])
    ->filterForPermissions($permissions);

// Filtrar por roles
$userRoles = collect(['admin', 'editor']);
$query = rk_navigation()
    ->newQuery()
    ->filterForRoles($userRoles);

// Filtrar para el usuario autenticado actual
$query = rk_navigation()
    ->newQuery()
    ->filterForCurrentUser();

3. Filtros de Estructura

Controlan la profundidad y estructura del árbol de navegación:

// Limitar profundidad a 2 niveles
$query = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard'])
    ->withDepth(2);

// Incluir grupos vacíos en los resultados
$query = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard'])
    ->withEmptyGroups(true);

4. Filtros de Usuario

Filtros específicos para usuarios:

// Para un usuario específico por ID
$query = rk_navigation()
    ->newQuery()
    ->forUser('user-123');

// Para el usuario autenticado (con manejo de errores)
$query = rk_navigation()
    ->newQuery()
    ->prepareForUser(); // Puede lanzar RuntimeException si no hay usuario autenticado

// Alternativa más segura para usuario actual
$query = rk_navigation()
    ->newQuery()
    ->filterForCurrentUser();

5. Filtros de Archivos

Controlan qué archivos de navegación se incluyen:

// Solo archivos de contextos específicos
$query = rk_navigation()
    ->newQuery()
    ->filterOnlyFiles(['headerDashboard']);

// Todos los archivos de todos los contextos
$query = rk_navigation()
    ->newQuery()
    ->filterAllFiles();

Ejemplos Prácticos Completos

Ejemplo 1: Navegación Principal con Permisos

$headerQuery = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard'])
    ->filterForPermissions($permissions)
    ->withDepth(3);

$headerItems = $headerQuery->get();

Ejemplo 2: Navegación Completa para Usuario Actual

$fullQuery = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard', 'footerDashboard'])
    ->filterForCurrentUser()
    ->withEmptyGroups(false);

$allItems = $fullQuery->all();

Ejemplo 3: Obtener Nodo Activo con sus Hijos

$fullQuery = rk_navigation()
    ->newQuery()
    ->loadContexts(['headerDashboard', 'footerDashboard'])
    ->filterForPermissions($permissions);

$activeNode = $fullQuery->getActiveNodeParentWithChildren();

Métodos Terminales

Los métodos terminales ejecutan la consulta y devuelven resultados:

Método	Descripción	Retorna
`get()`	Obtiene el árbol filtrado	`Collection`
`all()`	Alias de get()	`Collection`
`allFlattened()`	Obtiene estructura aplanada	`Collection`
`getSubBranch($id)`	Obtiene sub-rama específica	`Collection`
`getSubBranches($ids)`	Obtiene múltiples sub-ramas	`Collection`
`getForCurrentUser()`	Obtiene árbol para usuario actual	`Collection`
`getCurrentActiveNode()`	Obtiene nodo activo actual	`RkEntityInterface\|null`
`getActiveNodeParentWithChildren()`	Obtiene padre del nodo activo con hijos	`RkEntityInterface\|null`
`getBreadcrumbsForCurrentRoute()`	Obtiene migas de pan para ruta actual	`Collection`

Notas Importantes

Estado Singleton: Cada entidad mantiene una instancia singleton del orquestador, por lo que los filtros persisten hasta que se llama a newQuery().
Orden de Filtros: Los filtros se pueden aplicar en cualquier orden, pero se recomienda aplicar filtros de contexto primero.
Rendimiento: El sistema utiliza caché interno para optimizar consultas repetitivas.
Reinicio de Filtros: Usa resetFilters() para limpiar filtros sin crear una nueva consulta, o newQuery() para un reinicio completo.