Instalación

Requerimientos Mínimos

Antonella Framework necesita los siguientes elementos

GIT

Composer

PHP 7.0 o superior

En el Caso de Linux tienes que instalar el complemento PHP-ZIP

Para live testing será necesario conexión a base de datos MYSQL o MariaDB implementados en la consola

Instalación de Antonella Framework

Puedes instalarlo desde git (Debes instalarlo en una carpeta vacía)

 composer create-project --prefer-dist cehojac/antonella-framework-for-wp:dev-master tu-nombre-de-plugin 

o

composer create-project cehojac/antonella-framework-for-wp -s dev tu-nombre-de-plugin

colocando donde dice «tu-nombre-de-plugin» por el nombre del plugin que vas a crear.

Durante la instalación se preguntará si deseas instalar el sistema de plantillas Blade para tu proyecto.

You need add blade? (Template system)  Type 'yes' or 'y' to continue:

Luego

 cd tu-nombre-de-plugin

Estructura

El sistema de carpetas se mostrará de la siguiente manera:

Los archivos del Framework se encuentran en la carpeta SRC.

Los archivos de la vista Blade se encuentran en resources -> views-> template

Los helpers se encuentran en la carpeta src/Helpers

En el caso de realizar testing los archivos del WP de prueba se alojarán en la carpeta wp-test

El Namespace

Al momento de instalar el proyecto Antonnella creara un «namespace» aleatorio. Puedes cambiarlo en la consola

php antonella namespace TUNAMESPACE

donde en el lugar «TUNAMESPACE» debes colocar el nuevo nombre para el namespace

Si deseas generar otro namespace aleatorio solo debes poner en la consola

php antonella namespace

y automáticamente generará otro

Para llamar a las funciones dentro de los archivos controladores puedes hacerlo de la siguiente manera

$tu_variable= __NAMESPACE__.TuClase::TuFuncion;

Esta función puede ser reutilizado por otros plugins o addons.

Configuración

Para asignar el nombre del plugin sólo será nesesario modificar el archivo antonella-framework.php en la seccion Plugin name.

El archivo config.php contienen un sistema de arrays para configurar tu plugin de una manera fácil.

Variable Options

Esta variable permite introducir las variables que deseas insertar en wordpress

Ejemplo:

/*

* Plugins option

* storage in database the option value

* Array ('option_name'=>'default value')

* @example ["example_data" => 'foo',]

* @return void

*/

public $plugin_options=[

"version"=>"1.0",

"valor1" => "algun valor",

];

Variable language_name

Puedes indicar una única palabra para indicar la traducción. por defecto es «antonella» pero puedes cambiarla

/**

* Language Option

* define a unique word for translate call

*/

public $language_name='antonella';

Variable plugin_prefix

indica una única palabra para identificar el plugin. por defecto es «ch_nella» pero puedes cambiarse.

/**

* Plugin text prefix

* define a unique word for this plugin

*/

public $plugin_prefix='ch_nella';

Variable data_post

Con esto puedes controlar la llegada de las url tipo post. puedes indicar que si dentro de un post esta una variable que te interesa, invocar a una función que desees

/**

* POST data process

* get the post data and execute the function

* @example ['post_data'=>'CH::function']

*/

public $post=["admin"=>"TuClase::tufuncion"];
 

Variable data_get

Como en el post, si hay alguna variable que venga del get que te interese puedes invocar a una función

/**

* GET data process

* get the get data and execute the function

* @example ['get_data'=>'CH::function']

*/

public $get=["tu_variable_get","TuClase::TuFuncion"];

Variable add_filter

Aqui puedes agregar el filtro de WordPress que desees, pudiendo agregar la prioridad de la ejecución de la funcion y si acepta variables o no

/**

* add_filter data functions

* @input array

* @example ['body_class','CH::function',10,2]

* @example ['body_class',['CH','function'],10,2]

*/

public $add_filter=[

["init","TuClase::TuFuncion",10,1],

["init",["TuClase","TuFuncion"],10,1],

];

Variable add_action

Igual que con filter, puedes agregar acciones de WordPress

/**

* add_action data functions

* @input array

* @example ['body_class','CH::function',10,2]

* @example ['body_class',['CH','function'],10,2]

*/

public $add_action=[

["save_post","TuClase::TuFuncion",10,1],

["save_post",["TuClase","TuFuncion"],10,1],

];

Variable dashboard

Siguiendo la referencia para agregar apartados en el Escritorio de WordPress, se ha creado esta variable para configura llamando a la función que desees

/**

* Dashboard

* @reference: https://codex.wordpress.org/Function_Reference/wp_add_dashboard_widget

*/

public $dashboard=[

[

'slug'=>'tu_slug',

'name'=>'Dato que aparece en el escritorio de WP',

'function'=>'TuClase::TuFuncion',

'callback'=>'',

'args'=>'',

]

];

Variable plugin_menu

Aqui se configura el menu del plugin, es posible agregarlo como parte principal en el Menú del escritorio de WordPress o puedes que sea una subsección. depende de tu elección.

La configuración del menú va de la siguiente manera:

«path» del tipo array . si Deseas que vaya como menú principal debes indicar que es «Page»

"path"=> ["page"],

en caso que quieres se que sea una sub-pagina de algún apartado sería asi

"path"=> ["subpage","tools.php"],

en caso quieres que sea una opción de los ajustes de WordPress

"path"=>["option"],

«name» Es el nombre que se podrá como titulo del menu
«slug» es el identificador único de esta sección
«function» la función que deseas invocar cuando se accede a esta parte de menú

Puedes crear sub páginas dentro de la página principal

$plugin_menu=[

[

"path"=> ["page"],

"name"=>"My Custom Page",

"function"=>__NAMESPACE__."Admin::option_page",

// "icon" => "antonella-icon.png",

"slug"=>"my-custom-page",

"subpages"=>

[

[

"name"=>"My Custom sub Page",

"slug"=>"my-top-sub-level-slug",

"function"=>__NAMESPACE__."Admin::option_page",

]

];

El plugin tiene un ejemplo que puedes modificar a tu gusto.

Variable PostType

Aquí se configura la creación de un post Type, puedes hacer uno o varios desde este apartado.

public $post_types =[
[
'singular'=>'El nombre de tu post-type en singular como por ejemplo bicicleta',
'plural'=>'El nombre de tu post-type en plural como por ejemplo bicicletas',
'slug'=>'la url amigable que desees',
'translate'=>false,  // si quieres que se incluya una traducción de tu post type
'position'=>4, //la posicion en el menu de la administración
'taxonomy'=>['category'], //para agregar taxonomías a tu post type, estas taxonomías se crean desde aquí sólo con poner el nombre
'image'=>'', //icono de la imagen  -> debes guardarla en img y solo poner el nombre de la imagen con su extensión, también acepta iconos de dash-icon y un string basado en BASE64
'gutemberg' => true para mostrar el editor gutember en vez del clasico. Por defecto es true, Para mostrar en este PostType el editor clásico debe ser false el valor
],

Variables avanzadas para crear un PostType puedes agregar las variables «labels», «args» y «rewrite» entro del array y seguir las mismas subvariables de la creación de un Custom PostType  basado en la función registrer_post_type de WordPress

Variable Taxonomía

Aquí se configura la creación de taxonomías para PostTypes existentes o para crear taxonomías más complejas.

public $taxonomies = [
[
"post_type" => "", //nombre el PostType para asignar la taxonomía
"singular" => "",  //nombre de la taxonomía en singular
"plural" => "", // nombre de la taxonomía e n plural
"slug" => "", //nombre slug (amigable)
"gutemberg" => true, // para mostrar la taxonomía en el editor Gutemberg.
]

Puedes usar variables adicionales avanzadas «args», «rewrite», «labels» y «capacities» de la misma forma que en la función registrer_taxonomy de WordPress

Variable Widget

Para crear Widgets Sólo necesitas crear en la consola un nuevo Controlador del tipo Widget

php antonella Widget MiClaseWidget

donde MiClaseWidget es el nombre de la clase. Generará un archivo como en los controladores MiClaseWidget.php con el código necesario para empezar a programar

Luego en configuración debes agregar la clase en su sección

/**
         * Widget
         * For register a Widget please:
         * Console: php antonella Widget "NAME_OF_WIDGET"
         * @input array
         * @example public $widget = [__NAMESPACE__.'YouClassWidget']  //only the class
         */
        public $widgets=[
// aquí van las clases de los Widgets
];

Llamando a la configuración

En caso necesites algún dato de la configuración para tus funciones puedes hacer  lo siguiente:

$config= new __NAMESPACE__Config;
$options= $config->plugin_options;

Controladores por defecto

Antonella Framework tiene por defecto controladores que ordenan las funciones que deseas crear. tiene funciones por defecto el cual puedes usar en cualquier otro apartado de los controladores.

Init.php

En la función index por defecto puedes poner lo que necesites cada vez que se ejecuta el plugin.

Los POST y los GET son controlados desde Config.php en las opciones de GET y POST

AdminPageAdmin.php

Este archivo puedes colocar la vista de la página admin en caso necesitas crearlo.

Install.php

Install.php controlará todo lo referente a la instalación del plugin. como la creación de tablas dentro de la base de datos de WordPress. La creación de las opciones del plugin se configurar desde Config.php

Creando tablas

$options=[
[
"table"=>"tu_tabla",
"query" =>" id int(11) NOT NULL AUTO_INCREMENT, columna TEXT ",
],
];
$install= $this->table_make($options)

donde:

«table» es el nombre de la tabla

«query» son las columnas a crear siguiendo los patrones de MySQL siguiendo los patrones de column options

Puedes crear varias tablas en en array $options

la Variable $this es en caso que crees la funcion dentro del archivo Install.php, en caso contrario sería

$tables= new __NAMESPACE__.Install;
$tables->table_make($options);

Unistall.php

Aquí puedes poner tus funciones referentes cuando el plugin es borrado de WordPress. por defecto se borran las opciones de WordPress que usa este plugin y que se encuentra en Config.php

Users.php

Aquí puedes poner las funciones referentes a las opciones de usuarios de WordPress. por defecto genera las variables del usuario activado en ese momento

$data= new __NAMESPACE__.Users;
//puedes llamar las opciones de usuario de WP
$login_name= $data->user->user_login;

Creando tu controlador

en caso deseas crear tu propio controlador puedes hacerlo usando la consola de antonella

php antonella make TuControlador

donde «TuControlador» es el nombre de tu controlador.

Antonella consola creara un archivo en la carpeta src como TuControlador.php donde esta el código inicial para empezar

LLamando tu controlador

desde cualquier parte del plugin

$foo= new __NAMESPACE__.TuControlador
$foo->TuFuncion(); //para llamar a una función
$foo->data; //para llamar a una variable de la clase

Creando Widgets

Antonella te ayuda a crear Widgets usando la consola

php antonella widget EjemploWidget

donde EjemploWidget es el nombre de tu Widget

Antonella creará un archivo llamado EjemploWidget.php en la carpeta src con lo necesario para crear tu widget.

Registrar mi Widget

Para ello debes ir al archivo Config.php e ir a la sección $widgets

/**
* Widget
* For register a Widget please:
* Console: php antonella Widget "NAME_OF_WIDGET"
* @input array
* @example public $widget = [__NAMESPACE__.'YouClassWidget'] //only the class
*/
public $widgets=[__NAMESPACE__.'EjemploWidget'];

Creando Helpers

Desde la versión 1.6 de Antonella es posible crear Helpers. Los helpers son funciones comunes que puedes invocar desde cualquier clase.

Helper ya existentes en Antonella Framework

view: para mostrar las plantillas Blade en caso que hayas instalado Blade. más detalles en el Apartado Blade.

Registrar mis Helpers

Puedes crear tus propios helpers con el comando

php antonella helper mihelper

donde mihelper es el nombre del helper que vas a crear. Antonella crea un archivo «mihelper.php» en la carpeta Helpers

Dos vías de trabajo

Antonella Framework sigue el sistema PSR-4 para poder crear un proyecto grande en equipo pero también es posible poder generar un solo controlador que maneje lo necesario para tu plugin. Aquí explicamos las dos formas de de trabajar:

Usando el sistema de archivos del framework.

Cada cosa en su sitio y cada sitio en su lugar.  El sistema de archivos ubicados en la carpeta src contiene controladores para apartados específicos de un plugin estandar de WordPress. puedes crear funciones dentro de su controlador e incluirlo dentro de la configuración (srcconfig.php). Este sistema es recomendable para trabajos en equipos.

Podemos agregar shortcodes (shortcodes.php)

Agregar funciones al instalar y desinstalar (Install.php y Unistall.php)

Agregar funciones al iniciar el plugin (Init.php)

Agregar funciones referente a los datos del usuario registrado (Users.php)

Agregar funciones referente al PostType (PostTypes.php)

Creando Controladores propios

Si tu plugin es muy sencillo puedes usar un solo archivo creando un controlador y creando tus funciones en ese controlador

puedes crearlo desde la consola con Antonella console:

php antonella make TuControlador

Se creará un controlador con una clase con el mismo nombre de tu archivo creado (en este ejemplo TuControlador.php)

<?php
namespace CH;
class TuControlador
{
     public function__construct()
     {


     }
}

Puedes crear tus funciones en la clase y luego agregarlos en config.php

por ejemplo creas la funcion Mifuncion() dentro de tu controlador y deseas que sea una parte del init de WordPress

dentro de config.php

public $add_action=['init','CHTucontrolador::Mifuncion'];

Consola Antonella

Antonella Framework contiene su propia consola al mismo estilo de artisan de Symfony el cual tiene las siguientes opciones:

Crear controlador

php antonella make TuControlador

Creará automáticamente un archivo .php en la carpeta src con el nombre TuControlador.php con el código necesario para empezar a programar.

Crear Helper

php antonella helper TuHelper

Creará automáticamente un archivo .php en la carpeta src/Helper con el nombre TuHelper.php con el código necesario para empezar a programar tu helper

Cambiar namespace

El namespace de php es necesario para programar con el framework. por defecto es CH pero puedes cambiarlo

php antonella namespace TUNAMESPACE

Donde TUNAMESPACE es el nombre nuevo que  deseas asignar

En caso de usar Antonella framework en más de un plugin en el mismo WordPress será necesario que tengan Namespace distintos.

Puedes crear Namespaces aleatorios si no le pones un nombre

php antonella namespace

Antonella se encargará de generar uno.

Crear Widgets

php antonella widget  EjemploWidget

Genera un archivo php en la carpeta src con el nombre EjemploWidget.php con el código necesario para crear tu widget

Testing

Previamente debes configurar tu archivo .env con los accesos a la base de datos para testing

php antonella serve

Crea un entorno de desarrollo, instala WordPress localmente y lo pone a funcionar en el servidor 8010 (http://localhost:8010), instala en ese WordPress el plugins activado y funcionando en la carpeta wp-test

php antonella test refresh

Refresca la información del plugin en el WordPress de test.

en caso deseas cambiar la información de la base de datos del archivo .env debes forzar la recarga del archivo wp-config.php con

php antonella test refresh force

Quitando y añadiendo Blade

Antonella Framework viene con la opción de instalar blade . Si deseas usarlo puedes agregarlo con este comando

php antonella add blade

Así mismo si deseas removerlo:

php antonella remove blade

Exportar tu plugin

php antonella makeup

genera un archivo .zip del plugin con los archivos necesarios para que funcione el plugin.

Ayuda

Antonella dispone de un sistema de ayuda

php antonella help

Paquetes Externos

Antonella Framework acepta paquetes de terceros ya sean hechos para WordPress o no.

Puedes encontrar una gran variedad en Packagist.org y poder invocarlos desde el archivo composer.json. Estos paquetes se guardarán en la carpeta Vendor.

Aviso: el uso se paquetes externos aumenta considerablemente el tamaño de tu plugin y si es un paquete no seguro puede llevar a huecos de seguridad en tu WordPress por lo que se recomienda usarlos sólo si es necesario y si son paquetes de confianza

Ejemplo:

Si estamos acostumbrados con el paquete Eloquent para el control de base de datos de WordPress o para invocar una base de datos externa podemos hacer lo siguiente:

buscamos en Packagits «eloquent for WordPress»

lo agregamos a nuestro composer.json

{

"require": {

"tareq1988/wp-eloquent": "dev-master"

}

}

y luego ejecutamos composer

composer update

Con esto ya podemos utilizar Eloquent para nuestro WordPress

$db = WeDevsORMEloquentDatabase::instance();

var_dump( $db->table('users')->find(1) );

var_dump( $db->select('SELECT * FROM wp_users WHERE id = ?', [1]) );

var_dump( $db->table('users')->where('user_login', 'john')->first() );

Agregar Plugins a nuestro proyecto como módulos

Puedes hacer que cualquier plugin del repositorio de WordPress sea parte de tu plugin como un módulo

Desde https://wpackagist.org puedes obtener la linea que necesitas agregar en la parte «require» de tu archivo composer.json

Como los plugins de WordPress no cumplen con el sistema de desarrollo PSR-4 Debes agregar el archivo de inicio del plugin en la sección «autoload» de tu archivo composer.json.

"autoload": {
        "psr-4": {"CH\": "src/"},
        "files":{["vendor/contact-form-7/wp-contact-form-7.php"]}
    },

en caso quieras agregar ContactForm7 como un módulo

Video explicativo: https://www.youtube.com/watch?v=qv-rHY_4zhk

Crear Paquetes para Antonella Framework

Es posible crear paquetes para WordPress y usarlo con AntonellaFramework.

Ejemplos:

https://github.com/ArroyoLabs/erdiko-wordpress

https://packagist.org/packages/drewjbartlett/wordpress-eloquent

Para ellos es recomendable seguir la documentación de https://packagist.org

Puedes seguir el curso de creación de paquetes para php de styde

Puedes publicar tu paquete dentro de la documentación de Antonella Framework enviando el link al email packages@antonellaframework.com