Download the PHP package flowstore/lookup without Composer

Lookup (Paquete Laravel)

Qué es: Capa agnóstica para consultar APIs externas por "canal" (ecommerce/ERP/marketplace) y convertir respuestas en DTOs de dominio unificados. Se usa para iniciar integraciones (probar conexión, traer datos base, etc.). No persiste ni configura integraciones.

Instalación

• Requerimientos: PHP ^8.1+, Laravel ^9|^10|^11|^12.

• Instala vía Composer:

• Publica la configuración:

Configuración

Archivo config/lookup.php:

• providers: mapa channel_key => ClaseProvider.
• mappers: mapa channel_key => [entity => ClaseMapper].
• conventions: namespaces por defecto para resolución por convención.
• http: timeouts y retries por defecto para el cliente HTTP.

Contratos principales

• LookupProviderInterface: resources(), testConnection(IntegrationContext), lookup(IntegrationContext, entity, params).
• EntityMapperInterface<TDomain>: entity(), map(payload, IntegrationContext): TDomain.
• IntegrationContext: DTO con channelKey y credentials.
• IntegrationContextResolver: contrato que la app host implementa para resolver un contexto desde un integrationId.

Resolución y orquestación

• LookupProviderResolver: resuelve Provider por channel_key usando config('lookup.providers') o la convención App\\Lookup\\Providers\\{Canal}LookupProvider.
• EntityMapperResolver: resuelve Mapper por channel_key + entity usando config('lookup.mappers') o la convención App\\Lookup\\Mappers\\{Canal}\\{Entidad}Mapper.
• PerformLookupAction: invoca provider->lookup(...) y mapea con mapper->map(...).
• LookupService: resuelve contexto (si se usa IntegrationContextResolver) y devuelve el DTO de dominio.

Resolución de contexto (configurable)

El paquete es agnóstico de tu modelo. Define cómo construir IntegrationContext desde el request:

Si usas el resolver genérico Eloquent con IntegrationTenant:

Modelo sugerido:

El controlador del paquete leerá el id desde config('lookup.context.id_param') (por defecto integration_id) y resolverá el contexto usando el resolver configurado o el resolver Eloquent si se define context.eloquent.model.

HTTP (LookupController)

• La ruta se habilita por defecto al instalar el paquete.
• Endpoint por defecto: POST /tenant-integrations/lookup (middleware api).
• Puedes deshabilitar u overrides en config/lookup.php:

Ejemplo de request (POST JSON):

Ejemplo de respuesta:

Nota: Debes implementar y bindear IntegrationContextResolver para traducir integration_id a IntegrationContext.

Test de conexión (TestConnectionController)

• Endpoint por defecto: POST /tenant-integrations/test-connection

• Body (JSON):

• Respuesta:

• Requiere un IntegrationContextResolver configurado (propio con context.resolver o genérico con context.eloquent.model).
• Ajustes en config/lookup.php:

Puntos de extensión

• Agregar un canal: crear App\\Lookup\\Providers\\{Canal}LookupProvider y registrarlo en config/lookup.php (o seguir la convención).
• Agregar una entidad: crear App\\Lookup\\Mappers\\{Canal}\\{Entidad}Mapper y registrarlo (o usar la convención).
• testConnection(...) permite "ping" de credenciales antes de usar lookup.

Comando de scaffolding

Contribuir

• Issues y PRs en https://github.com/flowstore/lookup.
• Ejecuta tests y static analysis antes de commitear:

Crea stubs para Provider y/o Mapper en tu app (app/Lookup/...).

Buenas prácticas

• Evita dependencia dura a modelos: usa IntegrationContext o implementa IntegrationContextResolver en tu app.
• Usa el Http Client de Laravel con timeouts/retries; el paquete provee un AbstractLookupProvider de ayuda.
• Mantén el retorno como DTO de dominio consistente y documentado por entidad.

Uso en la app host

O vía HTTP con el LookupController opcional.

IntegrationContext (qué es y cómo personalizar)

IntegrationContext es un DTO inmutable que describe el contexto de una integración:

• channelKey (string): identifica el canal (p.ej. shopify, mercadoLibre).
• credentials (array<string, mixed>): credenciales y datos necesarios para llamar al canal (token, apiKey, sellerId, etc.).

Se utiliza en LookupProviderInterface::testConnection(...) y lookup(...), y también en EntityMapperInterface::map(...) para proveer contexto al mapeo.

Personalización:

• Cambiar el parámetro de ID de entrada (nombre del campo en el request):

En este caso, el controlador leerá tenant_id en el body.

• Proveer tu propio resolver (sin Eloquent genérico):

Regístralo por configuración (no hace falta bind manual):

• Resolver genérico con Eloquent (sin escribir una clase):

Sugerencia de modelo:

Ejemplo de request con tenant_id:

Persistencia desde providers (helpers)

Para facilitar inserciones/actualizaciones en tus modelos Eloquent desde un provider custom, AbstractLookupProvider expone métodos protegidos que usan ModelWriter internamente:

• persistCreate(string $modelClass, array $attributes): Model
• persistUpdateOrCreate(string $modelClass, array $where, array $attributes): Model
• persistUpsert(string $modelClass, array $rows, array $uniqueBy, array $update): int

Ejemplos:

Notas:

• modelClass es el FQCN del modelo (App\Models\...).
• Asegúrate de que tu modelo tenga fillable/casts adecuados para los attributes.
• persistUpsert sigue la firma de Eloquent\Builder::upsert($rows, $uniqueBy, $update).