En este nuevo escenario, un framework no solo necesita estar actualizado para los desarrolladores, sino que también debe ofrecer a estos nuevos agentes el contexto necesario para entender cómo debe utilizarse. Con ese objetivo nace el repositorio KumbiaPHP Agent Skills, una nueva iniciativa de la comunidad para preparar el ecosistema para esta nueva etapa del desarrollo de software.

https://github.com/KumbiaPHP/agents-skills

¿Qué son las KumbiaPHP Agent Skills?

Las KumbiaPHP Agent Skills son un conjunto de instrucciones estructuradas diseñadas para que los agentes de inteligencia artificial puedan trabajar correctamente con el framework. A diferencia de la documentación tradicional, que está pensada para humanos, las Agent Skills están diseñadas para responder las dudas clave de los agentes, indicándoles cuándo usar una funcionalidad específica, qué decisiones arquitectónicas deben respetar, las convenciones propias del framework y cómo evitar errores conceptuales al generar código. Estas habilidades utilizan el estándar abierto Agent Skills, basado en archivos SKILL.md alojados dentro de carpetas especializadas.

Independencia de proveedores

El repositorio KumbiaPHP Agent Skills no está ligado a ninguna herramienta específica. Al no depender de asistentes concretos como Claude, GitHub Copilot, OpenCode o Codex, se convierte en una capa de conocimiento reutilizable para cualquier sistema compatible con el estándar. El objetivo no es crear una integración cerrada, sino construir una base de conocimiento universal para la IA aplicada a KumbiaPHP.

Primeras KumbiaPHP Agent Skills disponibles

La primera versión del repositorio incluye cuatro Agent Skills fundamentales:

1. Crear controladores (kumbiaphp-create-controller)

Define cómo deben crearse y modificarse los controladores en el framework. Instruye a la IA para que revise los controladores existentes, respete la jerarquía de AppController y mantenga la lógica de negocio estrictamente en los modelos. Al evitar la sobrecarga del controlador, esta Skill garantiza que el código generado mantenga siempre una arquitectura MVC limpia y ordenada.

2. Crear modelos (kumbiaphp-create-model)

Orientada a los modelos basados en ActiveRecord, esta instrucción guía a la IA en la revisión del esquema de la base de datos y en el uso de los patrones nativos del framework. Al enseñarle a evitar capas innecesarias —como repositorios externos— y a adaptarse al código del proyecto, su principal beneficio es asegurar que todas las soluciones respeten fielmente el estilo nativo de KumbiaPHP.

3. Crear vistas (kumbiaphp-create-view)

Esta habilidad define cómo trabajar con las vistas .phtml. Obliga al agente a revisar el controlador asociado, a aprovechar los layouts y helpers existentes, y a evitar la inclusión de lógica de negocio en la interfaz. El resultado directo de estas reglas es la generación de vistas mucho más limpias, coherentes y con una separación estricta del patrón MVC.

4. ActiveRecord (kumbiaphp-work-with-active-record)

Es la Skill más completa del sistema y abarca la formulación de consultas, paginación, relaciones, validaciones y operaciones CRUD. Además, incorpora reglas de seguridad vitales, educando a la IA sobre el control de campos permitidos y la precaución con las consultas dinámicas, mientras evita malas prácticas heredadas de otros ORM. Esto proporciona un equilibrio perfecto entre la seguridad de los datos y la consistencia general del framework.

Principios KISS, DRY y MVC en la IA

Estas directrices refuerzan los principios fundamentales de KumbiaPHP, asegurando que la IA aplique la filosofía KISS (Keep It Simple), DRY (Don’t Repeat Yourself), mantenga el patrón MVC bien separado y priorice el uso de las APIs nativas del framework. Adicionalmente, exigen que los agentes verifiquen la versión real de KumbiaPHP antes de asumir comportamientos, previniendo los clásicos errores que ocurren cuando la IA mezcla funciones de distintas versiones de PHP u otros frameworks.

KumbiaPHP Agent Skills y el futuro del framework

Este repositorio no es un experimento aislado, sino una evolución natural del ecosistema KumbiaPHP. Hoy en día, no basta con que un framework sea estable, esté bien documentado y se mantenga actualizado; también debe ser comprensible para los agentes de IA, compatible con herramientas de desarrollo asistido y estar estructurado para su consumo automático. Esto introduce un concepto vital para la supervivencia del software: el contexto del framework también debe mantenerse actualizado para las máquinas.

Las KumbiaPHP Agent Skills representan un cambio importante en la forma en que los frameworks se preparan para el futuro. Ya no basta con documentar para humanos; ahora también es indispensable documentar para los agentes de inteligencia artificial. Con este repositorio, KumbiaPHP da un paso al frente y se posiciona como un framework completamente preparado para la nueva generación de herramientas de desarrollo asistido por IA.

https://github.com/KumbiaPHP/agents-skills

https://agentskills.io/specification

La entrada KumbiaPHP Agent Skills: IA para el framework PHP se publicó primero en KumbiaPHP Framework PHP en español.

¿Qué es un chatbot inteligente?

Un chatbot con PHP es un asistente virtual que usa inteligencia artificial para simular una conversación natural con usuarios, realizando tareas como responder preguntas, agendar citas, brindar soporte técnico y más. Implementar un chatbot inteligente utilizando PHP puede potenciar significativamente tu aplicación web.

Veremos paso a paso cómo configurar las dependencias, conectar con el modelo GPT-4 y construir una interfaz simple que permita interactuar con el asistente directamente desde tu aplicación web.

Herramientas recomendadas para crear chatbots con PHP

• OpenAI API: Facilita el acceso a modelos avanzados como GPT-4 para procesamiento de lenguaje natural y es ideal para construir un chatbot con PHP.

• Dialogflow: Servicio gestionado de Google que simplifica la creación de interfaces conversacionales y puede integrarse fácilmente como chatbot con PHP.

• Rasa: Alternativa open source para chatbots personalizados y con mayor control, perfecta para crear un chatbot con PHP.

Creando un chatbot con PHP y KumbiaPHP usando la API de OpenAI

Paso 1: Instalar dependencias

Usa Composer para instalar la librería oficial de OpenAI para tu chatbot con PHP (Packagist de
OpenAI PHP):

composer require openai-php/client

Paso 2: Configuración específica para OpenAI

Crea un archivo específico para la configuración en config/openai.php para tu chatbot con PHP:

<?php

return [
    'api_key' => 'TU_API_KEY',
    'model' => 'gpt-4-turbo',
    'systemPrompt' => 
        'Eres un asistente útil. Te llamas Kumbita y amas Kumbiaphp',
];

Paso 3: Crear modelo para lógica de OpenAI

Crea el archivo app/models/open_ai_model.php, esencial para desarrollar un chatbot con PHP:

<?php

use \OpenAI\Client;

/**
 * OpenAI Service Model
 */
class OpenAiModel
{
    /**
     * @var OpenAiModel|null Instancia única de la clase
     */
    private static ?OpenAiModel $instance;

    /**
     * @var Client El cliente OpenAI
     */
    private Client $client;

    /**
     * @var array Configuración de OpenAI
     */
    private array $config;

    /**
     * Constructor para otras config
     *
     * @param array Configuración (opcional)
     */
    public function __construct(?array $config = null)
    {
        $this->config = $config ?? Config::read('openai');
        $this->client = OpenAI::client($this->config['api_key']);
    }

    /**
     * Obtiene la instancia única del servicio
     *
     * @param array Configuración (opcional)
     * @return OpenAiModel
     */
    public static function getInstance(?array $config = null): self
    {
        return self::$instance ??= new self($config);
    }

    /**
     * Obtiene el cliente OpenAI
     * 
     * @return Client
     */
    public function getClient(): Client
    {
        return $this->client;
    }

    /**
     * Envía un mensaje a OpenAI y recibe la respuesta
     * 
     * @param string $message El mensaje del usuario
     * @param string $systemPrompt El prompt del sistema (opcional)
     *
     * @return string La respuesta del modelo
     */
    public function sendMessage(string $message, ?string $systemPrompt = null): string
    {
        $response = $this->client->chat()->create([
            'model' => $this->config['model'],
            'messages' => [
                [
                  'role' => 'system',
                  'content' => $systemPrompt ?? $this->config['systemPrompt']
                ],
                [
                  'role' => 'user',
                  'content' => $message
                ],
            ],
        ]);

        return $response->choices[0]->message->content;
    }
}

Paso 4: Crear controlador Chatbot en KumbiaPHP

<?php

class ChatbotController extends AppController
{
    /**
     * Muestra el chatbot
     */
    public function index()
    {
    }

    /**
     * Endpoint para manejar mensajes del chatbot
     */
    public function message()
    {
        View::select(null, 'json');

        $message = Input::post('message');

        $this->data = match ($message) {
            null, '' => [],
            default =>  ['reply' => OpenAiModel::getInstance()->sendMessage($message)],
        };
    }
}

Paso 5: Crear la vista del chatbot en KumbiaPHP

Crea la vista index.phtml en app/views/chatbot/ para interactuar fácilmente con tu chatbot con PHP:

<section id="aibot">
    <h1>Chatbot Inteligente con PHP y KumbiaPHP</h1>

    <div id="chatResponse">
        <p>
            <b>Kumbita:</b> Hola, me llamo Kumbita. ¿Qué quieres saber hoy?
        </p>
    </div>

    <?= Form::open('', 'POST', 'id="chatbot"') ?>
    <?= Form::text('message', 'placeholder="Escribe tu pregunta" autofocus') ?>
    <?= Form::submit('Enviar', 'class="btn btn-primary"') ?>
    <?= Form::close() ?>
</section>

<script>
    document.getElementById("chatbot").addEventListener("submit",
        function(event) {
            event.preventDefault();
            sendMessage();
        });

    const messageEl = document.getElementById('message');
    const chatResponse = document.getElementById('chatResponse');
    const btnSubmit = document.querySelector('#chatbot [type="submit"]');
    const speech = 'speechSynthesis' in window ? new SpeechSynthesisUtterance() : null;
    const apiError = "Lo siento, parece que hay un error al conectar a la API";

    speak("Hola, me llamo Kumbita. ¿Qué quieres saber hoy?", "es");

    function sendMessage() {
        const message = messageEl.value;
        if(message.trim() === '') return;
        btnSubmit.disabled = true;
        messageEl.disabled = true;
        chatResponse.innerHTML += `<p><b>Tu:</b> ${message}</p><div id="loading"></div>`;
        chatResponse.scrollTop = chatResponse.scrollHeight;

        fetch('/chatbot/message', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded',
                    'Accept': 'application/json'
                },
                body: 'message=' + encodeURIComponent(message)
            })
            .then(response => response.json())
            .then(data => {
                response(data.reply ?? "");
            })
            .catch(error => {
                console.log(error);
                response(apiError);
            })
            .finally(() => {
                btnSubmit.disabled = false;
                messageEl.disabled = false;
                messageEl.value = '';
                messageEl.focus();
            });
    }

    function response(message) {
        speak(message);
        document.getElementById('loading').remove();
        chatResponse.innerHTML += `<p><b>Kumbita:</b> ${message}</p>`;
        chatResponse.scrollTop = chatResponse.scrollHeight;
    }

    function speak(text, lang = navigator.language) {
        if(!speech) return;
        speech.lang = lang
        speech.text = text
        window.speechSynthesis.speak(speech)
    }
</script>

<style>
    #aibot {
        max-width: 500px;
        margin: 0 auto;

        & h1 {
            text-align: center;
        }

        & #chatbot {
            display: flex;
            margin-top: 1em;
        }

        & #message {
            flex: 1;
            border-radius: 2rem 0 0 2rem;
            padding: 0.5em 1em;
            box-shadow: none;

            &:focus {
                outline: none;
            }
        }

        & [type="submit"] {
            flex: 0;
            border-radius: 0 2rem 2rem 0;
            box-shadow: none;
            
            &:disabled {
                opacity: 0.5;
            }
        }

        & #chatResponse {
            margin: 20px auto 0;
            min-height: 60px;
            max-height: 400px;
            background: #f5f5f5;
            border-radius: 6px;
            padding: 1em;
            box-shadow: 1px 1px 5px #eee;
            overflow-y: auto;
            display: flex;
            flex-direction: column;

            & p {
                color: #333;
            }
        }
    }
    #loading {
        width: 12px;
        height: 12px;
        border-radius: 50%;
        display: block;
        margin:15px auto;
        position: relative;
        color: #9ab8ef;
        box-sizing: border-box;
        animation: animloader 1s linear infinite alternate;
    }

    @keyframes animloader {
        0% {box-shadow: -38px -6px, -14px 6px,  14px -6px;}
        33% {box-shadow: -38px 6px, -14px -6px,  14px 6px;}
        66% {box-shadow: -38px -6px, -14px 6px, 14px -6px;}
        100% {box-shadow: -38px 6px, -14px -6px, 14px 6px;}
    }
</style>

Ventajas de usar chatbots en aplicaciones PHP

• Disponibilidad 24/7.

• Respuestas inmediatas y personalizadas.

• Optimización de recursos humanos y reducción de costos operativos.

Este ejemplo constituye una base sólida para comprender cómo integrar inteligencia artificial en tus proyectos PHP con KumbiaPHP. A partir de aquí, puedes ampliarlo añadiendo manejo de historial de conversación, personalización de prompts del sistema, validaciones adicionales de entrada, o incluso mecanismos de seguridad para evitar abusos en el endpoint.

Al finalizar esta guía, tendrás un chatbot completamente funcional listo para integrarse en cualquier proyecto desarrollado con KumbiaPHP. Anímate a probarlo, experimentar con sus respuestas y descubrir el potencial de combinar la sencillez de PHP con la potencia de la inteligencia artificial. Si te ha resultado útil, comparte este artículo o deja tus comentarios en el blog para seguir mejorando juntos.

Agradecimientos

Agradecemos especialmente a @joanhey por tomarse el tiempo de revisar y mejorar el código de ejemplo, aportando sugerencias valiosas que ayudaron a hacerlo más claro y funcional para la comunidad de desarrolladores de KumbiaPHP.

La entrada Chatbots inteligentes en PHP con KumbiaPHP se publicó primero en KumbiaPHP Framework PHP en español.

Si estás buscando implementar un buscador avanzado de texto completo para KumbiaPHP con Meilisearch, este artículo te mostrará cómo hacerlo de manera sencilla, efectiva y escalable. Descubre cómo aprovechar todo el potencial de Meilisearch en tus aplicaciones KumbiaPHP, ofreciendo a tus usuarios búsquedas rápidas y resultados altamente relevantes.

¿Por qué utilizar un buscador avanzado de texto completo para KumbiaPHP con Meilisearch?

Implementar un buscador avanzado de texto completo para KumbiaPHP con Meilisearch permite llevar las capacidades de búsqueda de tus aplicaciones a otro nivel. Meilisearch es un motor de búsqueda rápido, potente y de fácil configuración, ideal para aplicaciones modernas que requieren búsquedas en tiempo real, autocompletado y manejo de grandes volúmenes de datos.
Además, gracias a sus capacidades de búsqueda semántica impulsada por inteligencia artificial, se pueden obtener resultados mucho más precisos incluso cuando las palabras de búsqueda no coinciden exactamente con los términos indexados.

Requisitos

Antes de comenzar a integrar un buscador avanzado de texto completo para KumbiaPHP con Meilisearch, verifica que tu entorno cumpla con los siguientes requisitos básicos:

• Tener una aplicación funcionando con KumbiaPHP 1.2 o superior.

• Tener PHP 8.0 o superior.

• Tener acceso al servidor o contenedor donde correrá Meilisearch.

• Instalar el cliente de Meilisearch para PHP con Composer:

composer require meilisearch/meilisearch-php \
guzzlehttp/guzzle \
http-interop/http-factory-guzzle:^1.0

• Instalar el nuevo ActiveRecord de KumbiaPHP si aún no lo tienes:

composer require kumbia/activerecord

Este nuevo ActiveRecord es un componente externo que puedes usar en cualquier proyecto PHP, y es requerido para que los modelos soporten los callbacks usados por el trait MeilisearchSearchable.

Configuración del Cliente Meilisearch

Crea el archivo default/app/config/meilisearch.php con la siguiente estructura:

<?php
/**
 * MeiliSearch configuration file.
 *
 * This file contains the configuration settings for connecting to MeiliSearch.
 */
return [
    'host' => 'http://127.0.0.1:7700', // Change the host
    'api_key' => '', // Change the key
];

Trait MeilisearchSearchableTrait

Crea el archivo default/app/libs/meilisearch_searchable_trait.php con el siguiente código:

<?php

use Meilisearch\Client;

/**
 * Trait MeilisearchSearchableTrait
 */
trait MeilisearchSearchableTrait
{
    /**
     * MeiliSearch client instance.
     */
    protected static ?Client $_meiliClient = null;

    /**
     * Retrieves the MeiliSearch client instance.
     */
    protected static function getMeiliClient(): Client
    {
        if (null !== self::$_meiliClient) {
            return self::$_meiliClient;
        }

        $config = \Config::read('meilisearch');
        if (!$config || !is_array($config)) {
            throw new \RuntimeException('MeiliSearch configuration not found in config file.');
        }
        $host   = $config['host'] ?? 'http://localhost:7700';
        $apiKey = $config['api_key'] ?? '';

        return self::$_meiliClient = new Client($host, $apiKey);
    }

    /**
     * Returns the index name. By default it returns the table name provided by the model.
     */
    protected static function searchableAs(): string
    {
        return static::getTable();
    }

    /**
     * Converts the model instance to an array for indexing.
     */
    abstract protected function toSearchArray(): array;

    /**
     * Callback executed after a model is created.
     * The new record is automatically added to the MeiliSearch index.
     */
    protected function _afterCreate(): void
    {
        self::getMeiliClient()
            ->index(static::searchableAs())
            ->addDocuments([$this->toSearchArray()]);
    }

    /**
     * Callback executed after a model is updated.
     * The updated record is synchronized in the MeiliSearch index.
     */
    protected function _afterUpdate(): void
    {
        self::getMeiliClient()
            ->index(static::searchableAs())
            ->updateDocuments([$this->toSearchArray()]);
    }

    /**
     * Deletes a record and synchronizes the deletion with the MeiliSearch index.
     */
    public static function delete($pk): bool
    {
        $deleted = parent::delete($pk);

        if ($deleted) {
            self::getMeiliClient()
                ->index(static::searchableAs())
                ->deleteDocument($pk);
        }

        return $deleted;
    }

    /**
     * Performs a search query on the MeiliSearch index.
     */
    public static function search(string $query, array $options = []): array
    {
        $results = self::getMeiliClient()
            ->index(static::searchableAs())
            ->search($query, $options);

        return $results->getHits();
    }

    /**
     * Bulk-imports existing records into the MeiliSearch index.
     */
    public static function importToMeilisearch(int $chunkSize = 500): void
    {
        $offset = 0;

        do {
            $records = static::filter("LIMIT $chunkSize OFFSET $offset");
            $data    = [];

            foreach ($records as $record) {
                $data[] = $record->toSearchArray();
            }

            if (!empty($data)) {
                self::getMeiliClient()
                    ->index(static::searchableAs())
                    ->addDocuments($data);
            }

            $offset += $chunkSize;
        } while (count($records) === $chunkSize);
    }
}

Ventajas del Trait MeilisearchSearchable

• Integración simple: Reutiliza fácilmente la funcionalidad en múltiples modelos.

• Automatización: Mantiene sincronizados automáticamente tus modelos con el índice de búsqueda.

• Flexibilidad: Puedes personalizar fácilmente el comportamiento de búsqueda por cada modelo.

• Inteligencia Artificial: Soporte para búsqueda semántica mediante integración con IA (OpenAI u otros proveedores).

Cómo utilizar en la práctica un buscador avanzado de texto completo para KumbiaPHP con Meilisearch

Paso 1: Implementación en Modelos

A continuación, integra el trait en tus modelos que extiendan de LiteRecord:

Ejemplo con Modelo Product

<?php

use Kumbia\ActiveRecord\LiteRecord;

class Product extends LiteRecord
{
    use MeilisearchSearchableTrait;

    protected static $table = 'products';

    protected function toSearchArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'description' => $this->description,
            'price' => $this->price,
        ];
    }
}

Ejemplo con Modelo Article

<?php

use Kumbia\ActiveRecord\LiteRecord;

class Article extends LiteRecord
{
    use MeilisearchSearchableTrait;

    protected static $table = 'articles';

    protected function toSearchArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'content' => $this->content,
            'author' => $this->author,
        ];
    }
}

Una vez implementado el trait en tus modelos, realizar búsquedas será simple y eficaz. Estos ejemplos prácticos ilustran claramente cómo aprovechar tu nuevo buscador avanzado de texto completo para KumbiaPHP con Meilisearch.

Paso 2: Realizar búsquedas fácilmente

Ahora puedes realizar búsquedas en tus modelos:

// Buscar productos
$products = Product::search('zapatos deportivos', ['limit' => 10]);

// Buscar artículos
$articles = Article::search('tecnología', ['limit' => 5]);

Paso 3: Importar datos existentes

Si ya tienes datos almacenados en tu base de datos, puedes importarlos fácilmente:

Product::importToMeilisearch();
Article::importToMeilisearch();

Ejemplo de Mielisearch con Controlador y Vista en KumbiaPHP

Paso 1: Crea el controlador

Controlador: app/controllers/products_controller.php

class ProductsController extends AppController
{
    public function search()
    {
        if (Input::hasPost('query')) {
            $this->results = Product::search(Input::post('query'));
        }
    }
}

Paso 2: Crea la vista

Vista: app/views/products/search.phtml

<h1>Buscar productos</h1>

<?php View::content(); ?>

<?= Form::open(); ?>
    <?= Form::text('query', 'placeholder="Buscar..."') ?>
    <?= Form::submit('Buscar') ?>
<?= Form::close(); ?>

<?php if (empty($results) && Input::post('query')): ?>
    <p>No se encontraron resultados.</p>
    <?php return 1 ?>
<?php endif; ?>

<h2>Resultados</h2>
<ul>
    <?php foreach ($results as $product): ?>
        <li>
            <strong><?= h($product['name']) ?></strong><br>
            <?= h($product['description']) ?><br>
            Precio: $<?= h($product['price']) ?>
        </li>
    <?php endforeach; ?>
</ul>

La combinación de KumbiaPHP con Meilisearch a través del trait MeilisearchSearchable te permite ofrecer una experiencia superior en búsquedas a tus usuarios. Con la posibilidad de usar IA para búsquedas semánticas, la calidad de los resultados se eleva aún más. La integración es simple, escalable y potente, haciendo que valga la pena el esfuerzo inicial.

¡Prueba esta integración y lleva tus búsquedas al siguiente nivel con KumbiaPHP y Meilisearch!

La entrada Buscador avanzado de texto completo para KumbiaPHP con Meilisearch se publicó primero en KumbiaPHP Framework PHP en español.