Las directivas son pequeños fragmentos de funcionalidad, que se invocan desde el flujo.

• Hay muchas directivas ya desarrolladas, que el cliente añade en el proceso de despliegue, y que puedes utilizar, para hacer log, para comprobar que un apiKey que envia el cliente es correcto, para hacer conexiones contra otro microservicio o API, etc.
• También puedes desarrollar tus propias directivas, e implementar la lógica que desees, se escriben en PHP, y no existe ninguna limitación, puedes usar todo el lenguaje.
• Desde dentro de una directiva, puedes acceder al estado, lo que te permite leer la request, y escribir la response a través del message, pasar información entre directivas a través de memory, alterar el flujo por medio de los groups. También leer/escribir a base de datos, disco, o redis. Hacer conexiones contra otros servidores y casi cualquier cosa que necesites.
• Desde el api.yaml, puedes pasar parámetros de configuración a las directivas.

Para utilizar una directiva ya existente en el cliente, por ejemplo, comprobar un api key, debemos editar el api.yaml de esta manera:

key: poems
endpoints:
    get /ping:  
        CheckKeyPatata:
            directive: CheckKey
            expected: patata
            current: $.message.header.api-key
        Ping:
            directive: Ping

En el endpoint, creamos un elemento al que podemos dar cualquier nombre, en este caso CheckKeyPatata, dentro del elemento usamos directive para referirnos a la directiva concreta que queremos ejecutar, en este caso CheckKey. Luego cada directiva puede admitir o no parámetros de configuración, en este caso admite expected, que es el token que tiene que enviar el cliente (y que debe ser el string "patata") y current, que es el valor del token que realmente está enviando el cliente, que será el de la cabecera api-key, gracias al alias.

Si quisiéramos crear nuestra propia directiva, por ejemplo, una directiva que dependiendo de un queryParam recibido, devuelva una respuesta u otra. Primero crearemos el fichero dentro de la carpeta Directives del API, quedando la estructura de directorios así:

	api.yaml
	Directives/MyDirective.php

Luego dotaremos a MyDirective de funcionalidad, esta será su forma:

    <?php /*dlv-code-engine***/

	$output = 'Hola hombre desconocido';

	$name = $state->message()->getQueryParam('myname');
	if ($name === 'isidoro') {
		$output = 'Hola creador';
	}

	$state->message()->setHeader('Content-Type','application/json');
	$state->message()->setBodyAsArray(
		'text' => $output
	);

Todas las directivas que hagas, deben tener el siguiente encabezado: <?php /*dlv-code-engine***/ . Luego lo que se hace es acceder a un queryParam llamado myname, en caso de que sea isidoro se devolverá un JSON al cliente con el texto 'Hola creador', en caso contrario se enviará 'Hola hombre desconocido'.

Luego invocarás a tu directiva igual que en el ejemplo anterior, eligiendo cualquier nombre para ella, por ejemplo MyCustomDirective:

key: poems
endpoints:
    get /ping:
        MyCustomDirective:
            directive: MyDirective

Puedes parametrizar tu directiva para que admita parámetros de configuración, por ejemplo, podemos pasar el nombre del queryParam desde el api.yaml así:

key: poems
endpoints:
    get /ping:
        MyCustomDirective:
            directive: MyDirective
            nameQueryParam: myname

Y recoger ese parámetro en la directiva usando el array $config, quedando el código así:

    <?php /*dlv-code-engine***/

	$output = 'Hola hombre desconocido';

	$name = $state->message()->getQueryParam($config['nameQueryParam']);
	if ($name === 'isidoro') {
		$output = 'Hola creador';
	}

	$state->message()->setHeader('Content-Type','application/json');
	$state->message()->setBodyAsArray(
		'text' => $output
	);

Una directiva puede llamar a otra directiva, de las ya existentes, o de las que tu mismo creas a partir de expresiones como estas:

    <?php /*dlv-code-engine***/

	CheckKey::run($state,[
	    'expected' => 'patata',
	    'current' => $state->message()->getHeader('api-key');
	]);

	MyDirective::run($state,[
		'nameQueryParam' => 'myname'
	]);

No existen limitaciones, puedes ejecutar cualquier lógica, acceder al estado, combinarlo con llamadas a otras directivas dentro de un bucle, lo que necesites, aunque es recomendable que desde el api.yaml, se vean rápidamente las directivas que se ejecutan para lograr una mayor comprensión, y cumplir con el principio de responsabilidad única, y no delegar toda la funcionalidad a una superdirectiva.

Ir a la home