🗂 05. Configuración avanzada

Personalización del archivo ziggy.php

El archivo de configuración ziggy.php es el corazón de la personalización de Ziggy. Este archivo se publica en tu directorio config cuando ejecutas el comando php artisan ziggy:generate. Veamos cómo puedes personalizarlo para adaptarlo a tus necesidades.

Estructura básica del archivo de configuración

<?php
// config/ziggy.php

return [
  // Rutas que se deben incluir en el objeto JavaScript
  'only' => [
      'login',
      'logout',
      'home',
      'api.*',
  ],

  // Rutas que se deben excluir del objeto JavaScript
  'except' => [
      'admin.*',
      'debug.*',
  ],

  // Grupos de rutas según el entorno
  'groups' => [
      'admin' => [
          'admin.*',
      ],
      'api' => [
          'api.*',
      ],
  ],

  // URL base para generar las rutas
  'url' => env('APP_URL'),

  // Configuración para entornos multilingües
  'locale' => true,
];

Opciones de configuración principales

La opción only te permite especificar qué rutas deben incluirse en el objeto JavaScript. Esto es útil para reducir el tamaño del objeto Ziggy y mejorar el rendimiento.

'only' => [
    'login',
    'logout',
    'home',
    'api.*',  // Incluye todas las rutas que comienzan con 'api.'
],

La opción except te permite especificar qué rutas deben excluirse del objeto JavaScript. Esto es útil cuando quieres incluir la mayoría de las rutas pero excluir algunas específicas.

'except' => [
    'admin.*',  // Excluye todas las rutas administrativas
    'debug.*',  // Excluye rutas de depuración
],

La opción groups te permite definir grupos de rutas que pueden ser cargados de forma independiente.

'groups' => [
    'admin' => [
        'admin.*',
        'users.*',
    ],
    'api' => [
        'api.*',
    ],
],

La opción url te permite especificar la URL base para generar las rutas.

'url' => env('APP_URL'),

Selección de rutas específicas para exportar

Una de las características más potentes de Ziggy es la capacidad de controlar qué rutas se exportan al frontend. Esto es crucial para:

Seguridad: Evitar exponer rutas sensibles al frontend
Rendimiento: Reducir el tamaño del objeto JavaScript
Organización: Mantener separadas las rutas según su propósito

Filtrado de rutas con only y except

<?php
// config/ziggy.php

return [
  'only' => [
      // Rutas específicas por nombre
      'users.index',
      'users.show',
      'products.*',  // Todas las rutas de productos

      // Rutas con patrones
      'api.v1.*',    // Todas las rutas de API v1
  ],
];

Ejemplo práctico: Separar rutas públicas y administrativas

<?php
// config/ziggy.php

return [
  'groups' => [
      'public' => [
          'login',
          'register',
          'password.*',
          'products.*',
          'cart.*',
          'checkout.*',
      ],
      'admin' => [
          'admin.*',
          'users.*',
          'roles.*',
          'permissions.*',
      ],
  ],
];

Para usar un grupo específico en tu frontend:

Blade
JavaScript

@routes('public')

// Generar el archivo para un grupo específico
// php artisan ziggy:generate --group=public

import route from './ziggy-public';

Añadir middleware o grupos de rutas según el entorno

Ziggy te permite configurar diferentes comportamientos según el entorno de ejecución de tu aplicación. Esto es especialmente útil cuando necesitas diferentes conjuntos de rutas para desarrollo, pruebas y producción.

Configuración específica por entorno

<?php
// config/ziggy.php

return [
  // Configuración base para todos los entornos
  'only' => [
      'login',
      'home',
      'products.*',
  ],

  // Configuraciones específicas por entorno
  'production' => [
      'except' => [
          'debug.*',
          'telescope.*',
      ],
  ],

  'local' => [
      'only' => [
          'login',
          'home',
          'products.*',
          'debug.*',  // Incluir rutas de depuración solo en local
          'telescope.*',
      ],
  ],
];

Uso con middleware

Puedes combinar Ziggy con middleware para controlar qué rutas se exponen según el usuario autenticado:

<?php
// app/Http/Middleware/ZiggyRoutesMiddleware.php

namespace AppHttpMiddleware;

use Closure;
use IlluminateHttpRequest;
use TightencoZiggyZiggy;

class ZiggyRoutesMiddleware
{
  public function handle(Request $request, Closure $next)
  {
      // Determinar qué grupo de rutas usar según el usuario
      $group = $request->user() && $request->user()->isAdmin()
          ? 'admin'
          : 'public';

      // Compartir las rutas con la vista
      view()->share('ziggy', new Ziggy($group));

      return $next($request);
  }
}

Registra el middleware en app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // Otros middleware...
        \App\Http\Middleware\ZiggyRoutesMiddleware::class,
    ],
];

Configuración para entornos multilingües

Ziggy ofrece soporte para aplicaciones multilingües, permitiéndote generar URLs que respeten el idioma actual de la aplicación.

Habilitar soporte multilingüe

<?php
// config/ziggy.php

return [
  // Habilitar soporte para localización
  'locale' => true,

  // O especificar un locale por defecto
  'locale' => 'es',
];

Uso con prefijos de idioma en las rutas

Si tu aplicación utiliza prefijos de idioma en las URLs (como /es/productos o /en/products), Ziggy puede manejar esto automáticamente:

Route::prefix('{locale}')
    ->middleware('locale')
    ->group(function () {
        Route::get('products', 'ProductController@index')
            ->name('products.index');
    });

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\App;

class LocaleMiddleware
{
    public function handle($request, Closure $next)
    {
        $locale = $request->route('locale');
        App::setLocale($locale);

        return $next($request);
    }
}

// Ziggy generará la URL con el locale actual
const url = route('products.index'); // /es/products (si el locale es 'es')

// O puedes especificar un locale diferente
const url = route('products.index', {}, {}, 'en'); // /en/products

Cambio dinámico de idioma

// Componente de selector de idioma
import { ref, watch } from 'vue';
import route from 'ziggy-js';

export default {
setup() {
  const currentLocale = ref('es');

  const changeLocale = (newLocale) => {
    currentLocale.value = newLocale;

    // Redirigir a la misma página pero con el nuevo idioma
    const currentRouteName = route().current();
    const currentParams = route().params;

    if (currentRouteName) {
      window.location.href = route(currentRouteName, currentParams, {}, newLocale);
    }
  };

  return {
    currentLocale,
    changeLocale
  };
}
};

Personalización avanzada del objeto Ziggy

Puedes extender o modificar el objeto Ziggy antes de pasarlo al frontend para casos de uso específicos:

<?php
// En un Service Provider o middleware

use TightencoZiggyZiggy;

$ziggy = new Ziggy;

// Añadir datos personalizados al objeto Ziggy
$ziggy->customData = [
  'user' => auth()->user() ? [
      'id' => auth()->user()->id,
      'permissions' => auth()->user()->permissions->pluck('name'),
  ] : null,
  'settings' => [
      'enableFeatureX' => config('features.x_enabled'),
      'apiTimeout' => config('api.timeout'),
  ],
];

// Compartir con la vista
view()->share('ziggy', $ziggy);

Luego, en JavaScript:

// Acceder a los datos personalizados
console.log(Ziggy.customData.settings.enableFeatureX);

// Comprobar permisos del usuario
const hasPermission = (permission) => {
  return Ziggy.customData.user &&
         Ziggy.customData.user.permissions.includes(permission);
};

if (hasPermission('edit-users')) {
  // Mostrar opciones de edición
}

Resumen de configuración avanzada

Importante

Usa only para limitar las rutas expuestas al frontend
Nunca expongas rutas administrativas o sensibles a usuarios no autorizados
Considera usar middleware para filtrar rutas según el usuario
No añadas información sensible al objeto Ziggy

🐝