Instalación

Requerimientos Mínimos

Antonella Framework necesita los siguientes elementos

GIT

Composer

PHP 8.0 o superior

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

Para Live testing será necesario tener instalado Docker

Instalación de Antonella Framework

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

 composer create-project cehojac/antonella-framework-for-wp 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

Testing en Localhost

Desde la vesrión 1.6 hay la posibilidad de probar tu plugin sin necesidad de subirlo a un servidor. Desde tu ordenador local puedes hacer una prueba de forma sencilla.

Necesario:

1. PHP
2. MySQL
3. PHPMyadmin (opcional)

Preparando el entorno

Debes de tener MySQL funcionando. Con la línea de comando o phpmyadmin debes crear una base de datos vacía y asignar un usuario para esa base de datos (puede ser el mismo admin de MySQL)

Dentro del proyecto de Antonella hay un archivo .ENV el cual aparece de esta forma

DBUSER=root

DBNAME=

DBPASS=

Debes rellenar esos campos correpondiente a:

DBUSER: El usuario de la base de datos que has creado y que tiene permisos totales.

DBNAME: El nombre de la base de datos que haz creado

DEBPASS: El password del usuario asignado a la base de datos

Esto debe ser rellenado sin comillas

Luego debes ejecutar en la consola

php antonella serve

Antonella Instalará un WordPress en tu proyecto dentro de la carpeta wp-test. Luego configurará WordPress, hará una copia del plugin, lo instalará y activará.

Creará un puerto para que puedas entrar al WordPress de prueba. Será el puerto 8010

Para entrar al panel de administración debes poner http://localhost:8010/wp-admin

El admin por defecto es

Usuario: test

Password: test

Testing

WordPress estará con el DEBUG activado por defecto, Podrás analizar y revisar los errores que PHP devuelva.

En caso deseas corregir un error debes ir a tu proyecto, hacer la correción y luego en la consola:

php antonella test refresh

Creará una copia del proyecto en forma de plugin y lo volverá a instalar en el WordPress de prueba.

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'];

APIs endpoins

Puedes crear rutas APIs en WordPress de manera simple.

Ejemplo: https://tuweb.com/wp-json/my-plugin-endpoint/v1/author/

La configuración está en Config.php

 /**
     * add APIs Endpoints
     * @param array
     * @example [['name','GET',__NAMESPACE__.'apiController::index']]
     * @example route: /wp-json/my-plugin-endpoint/v1/name
     */
    public $api_endpoint_name= "my-plugin-endpoint";
    public $api_endpoint_version=1;
    public $api_endpoints_functions=[
        ['author','GET',__NAMESPACE__.'ExampleController::example_api']
    ];

Configurando el nombre de tu endpoint, la versión y un listado de endpoints para poder llamar a funciones diferentes ubicados en tu plugin. Puedes crear todos los que desees siendo:

«author» el nombre de tu endpoint. puedes renombrarlo al que desees

«GET» el método para solicitar la API. Solo hay GET, POST y DELETE

«__NAMESPACE__.’ExampleController::example_api’» la función donde se ejecutará tu endpoint

Recuerda que la función debe ser llamada estáticamente

public static function example_api($data){
//este es un ejemplo creado desde un controlador como ExampleController.

$posts = get_posts( array(
                'author' => $data['id'],
              ) );

              if ( empty( $posts ) ) {
                return null;
              }

              return $posts[0]->post_title;
        }

}

Según la documentación de WordPress sobre este apartado, el resultado siempre se retorna en json de forma automática.

Si deseas saber más sobre los endpoints puedes hacerlo aqui Adding Custom Endpoints | REST API Handbook | WordPress Developer Resources

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

Creando Bloques de Gutenberg

Basándose en la documentación de WordPress para la creación de bloques de Gutenberg Se ha desarrollado un entorno fácil para crear cada bloque que desees.

Creando el bloque

Debes asignarle un nombre (sin espacios, con guiones si es necesario) y ejecutar en la consola

php antonella block nombre-de-mi-bloque

Creará en el archivo Config.php en el apartado de gutenberg

public $gutenberg_blocks =[

       'nombre-de-mi-bloque',
    ];

Además creará dos archivos dentro de la carpeta assets.

en la carpeta css el archivo nombre-de-mi-bloque.css para agregar los estilos que desees

en la carpeta js el archivo nombre-de-mi-bloque.js donde está un ejemplo para la creación de bloques.

wp.blocks.registerBlockType('antonella/nombre-de-mi-bloque', {
              title: 'nombre-de-mi-bloque',
              icon: 'smiley',
              category: 'common',
              attributes: {
                content: {type: 'string'},
                color: {type: 'string'}
              },
...

Dentro de WordPress aparecerá un nuevo bloque llamado «nombre-de-mi-bloque» con un ícono de una carita feliz que activará el bloque de ejemplo (hacer un h3 con colores)

Deberás tener conocimiento en javascript. Ya no será necesario que sepas PHP para poder registrar tu bloque.

Puedes agregar tantos bloques como desees.

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

Usando Docker para el desarrollo del plugin de WordPress

Puedes usar docker ahora con Antonella Framework.

Se ha usado un archivo de docker con la configuración adecuada para que funcione con el desarrollo. Con el puedes modificar tu plugin el tiempo real y se verá en el WordPress montado en Docker. Puedes cambiar la configuración para cambiar la versión de WP, mysql o PHP.

Requisitos

Tener instalado Docker Desktop. Download Docker Desktop | Docker

Ejecutar con Antonella Console.

php antonella docker

este comando levanta docker y monta WordPress en un contenedor Docker.

También puedes usar los comandos clásicos de docker-compose

docker compose | Docker Documentation

Archivo de configuración del contenedor:

version: '3'
services:
  mysql:
    image: mariadb
    restart: always
    ports:
      - 8081:3306
    environment:
      MYSQL_USER: wordpress
      MYSQL_ROOT_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
      MYSQL_PASSWORD: wordpress
  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - 80:80
    environment:
      MYSQL_USERNAME: 'user'
      MYSQL_ROOT_PASSWORD: 'password'
  wordpress:
    depends_on:
      - mysql
    image: wordpress:php8.0-apache
    ports:
      - 8080:80
    restart: always
    volumes:
      - ./:/var/www/html/wp-content/plugins/antonella-framework
    environment:
      WORDPRESS_DB_HOST: mysql:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    links:
      - mysql