Helpers

Los Helpers son bibliotecas de funciones clasificadas por categorías, éstas se cargan de una manera óptima y sólo las llamaremos cuando las necesitemos.

En la versión 1.0 se ha introducido unos pocos helpers, con el tiempo y apoyo de la comunidad se podrá agregar más Helpers, para contribuir con un Helper o más funciones para uno ya existente, puedes dejarlo en comentarios de un commit en github o enviarlos al correo prinick@ocrend.com y será colocado en las próximas versiones del Framework con sus respectivos créditos.

Arrays, Bootstrap, Emails, Files, Strings y Paypal, estos se ubican en ./core/kernel/helpers/

Cómo cargar un helper para usarlo

Para llamar a un Helper, sólo basta con cargarlo una única vez de la siguiente manera:

# Cargamos por ejemplo, el helper Strings
Helper::load('strings');

Y listo, ya podemos acceder a todas las funciones del helper strings, para acceder a una función solamente hay que hacer:

# En cualquier punto del programa después de que se haya cargado previamente el helper
echo Strings::amigable_time( time() - (60*60*24*2) );
# Absolutamente todas las funciones en los helpers, son métodos estáticos

El helper de arriba, nos mostraría en pantalla 'Hace 2 días', esta función amigable_time será detallada más abajo en la sección de Strings, pero basta con saber que si le pasamos un tiempo en segundos, nos devolverá cuánto tiempo ha pasado hasta ahora desde ese tiempo con ese formato amigable.

Podemos cargar todos los helpers que necesitemos ocupar.

Helper::load('strings');
Helper::load('arrays');
Helper::load('files');

Se puede apreciar que, para cargar el Helper solo hay que escribir en minúsculas preferiblemente, el nombre del archivo del helper ubicado en ./core/kernel/helpers/ que posee el mismo nombre que la clase misma.

Los helpers se pueden usar en cualquier punto del programa con esa simple llamada sólamente si estamos usando PlatesPHP como motor de plantillas, en caso de que estemos usando Twig la llamada de arriba solo nos da disponibilidad de uso en el controlador.

Usar un Helper en la vista cuando se usa TWIG

Para poder utilizar en la vista un helper, al momento de hacer su carga, debemos pasar como segundo parámetro al método load, la propiedad template del controlador actual.

# Cargamos por ejemplo, el helper Strings
Helper::load('strings',$this->template);

Haciendo esto, por ejemplo para llamar a un método del helper, debemos simplemente escribir.

{{ hash('abc123') }}

En la plantilla .twig y estaría listo. Esto sólamente aplica para los helpers Arrays, Bootstrap, Files y Strings ya que si abrimos cada uno de estos helpers, podemos ver que heredan de Twig_Extension y al final en el método getFunctions() están las funciones que podemos usar desde twig y como llamarlas.

Cómo añadir una función a un helper

Simplemente vamos al Helper, que están todos ubicados en ./core/kernel/helpers/ abrimos el archivo y creamos la función:

/**
  * ¿Qué hace?
  *
  * @param tipo_de_dato $nombre_de_parametro: ¿para qué se pasa este parámetro?
  *
  * @return tipo_de_dato ¿qué es ese dato que retorna? (si no retorna nada basta poner void)
*/
#( si no devuelve nada, o más de un tipo de dato no colocar nada en 'tipo_dato_devuelto' )
final public static function mi_funcion(tipo_de_dato $parametro) : tipo_dato_devuelto {
  #... todo el código
}

Ahora para utilizar la función, cuando cargamos el helper en donde creamos la función, solo hacemos:

ElHelper::mi_funcion();

En caso de que usemos PlatesPHP y queramos usar la función en la vista el código anterior funciona, pero no lo hará si nuestro motor es Twig, para eso, en el punto de abjo se explica cómo crear un helper en forma de extensión para Twig, si ya nuestro helper tiene esas características, la creación de la función se hace de la misma manera, salvo por un paso extra que es, editar el métood getFunctions() sólamente si estamos usando twig y queremos que esa función esté disponible en la vista.

public function getFunctions() : array {
    return array(
        #nombre_de_la_funcion_en_twig es el nombre que usaremos desde twig para llamar a la función.
        #mi_funcion es el nombre de la función que cree en el helper, que será ejecutada cuando se llame desde twig a 'nombre_de_la_funcion_en_twig'
        new Twig_Function('nombre_de_la_funcion_en_twig',array($this,'mi_funcion'))
    );
}

Cómo crear mi propio helper

Es importante no salirse del contexto, los helpers son bibliotecas de funciones con una categoría, si creamos un helper llamado XML por ejemplo, eso nos da a entender que lo único que contendrá ese helper, es funciones encargadas de algún manejo relacionado con XML.

Para crear un helper, nos vamos ./core/kernel/helpers/ y colocamos el nombre del archivo igual al nombre del helper, es importante que la primera letra esté en mayúsculas.

Por ejemplo creamos ./core/kernel/helpers/MiHelper.php, este helper no será usado en twig y no pretendemos usarlo en una vista

# Seguridad
defined('INDEX_DIR') OR exit('Ocrend software says .i.');

//------------------------------------------------

final class MiHelper {

  #... todas las funciones aquí

}

Si en cambio creamos con éste código:

# Seguridad
defined('INDEX_DIR') OR exit('Ocrend software says .i.');

//------------------------------------------------

final class MiHelper extends Twig_Extension {

  #... todas las funciones aquí

    public function getFunctions() : array {
        #... código aquí documentado arriba
    }

    public function getName() : string {
        return 'ocrend_framework_helper_mi_helper';
    }

}

Con ese código, estamos preparando al Helper para que sea una extensión de Twig y podamos usar sus métodos en la plantilla de Twig, esto es sólamente necesario si usamos twig y queremos que las funciones de nuestro helper estén disponible en las vistas. Para crear funciones, debemos ver el punto de arriba.

Ahora para utilizar nuestro helper, solo hay que cargarlo cuando lo necesitemos.

Helper::load('mihelper');
MiHelper::funcion_en_el();