Plugins

O que é um plugin

Um plugin é um módulo autocontido dentro de plugins/<nome>/: tem seus próprios controladores, modelos, widgets, endpoints de API, templates, traduções, permissões, menu do painel e regras de reescrita. O SitioYa traz, entre outros, noticias, clasificados, mensajes, stock, tablas e multidomain.

Criar um

./app/bin/create-plugin.sh tienda

Cria esta estrutura:

plugins/tienda/
├── config/
│   ├── config.php          'enabled' => true
│   ├── permissions.php     regras, papéis e atribuições
│   ├── menu.php            itens do menu do painel
│   ├── rewrite.php         regras de reescrita
│   ├── domains/            sobrescritas por domínio
│   └── locales/{es,en,pt}/ traduções
├── src/
│   ├── Controllers/        (Admin/, Ajax/…)
│   ├── Models/
│   ├── Widgets/
│   ├── Api/                endpoints: plugins.tienda.<classe>.<método>
│   ├── Components/  Hooks/  Libraries/
└── webroot/
    ├── css/  js/
    └── templates/          admin/, front/, widgets/

Ativação

PluginsManager::getInstalledPlugins() percorre plugins/ em cada requisição e ativa os que tiverem 'enabled' => true em config/config.php. Cada domínio pode mudar isso:

<?php
// plugins/tienda/config/domains/meusite.com/config.php
$CONFIG = ['enabled' => false];

A lista de plugins ativos fica em PluginsManager::$installedPlugins. O restante de config.php é lido com:

PluginsManager::readPluginConfig('tienda', 'moeda', 'BRL');
PluginsManager::writePluginConfig('tienda', 'moeda', 'USD');

URLs

O primeiro segmento da URL (depois de admin/, se houver) seleciona o plugin:

URL	Controlador
`/tienda/carrito`	`plugins/tienda/src/Controllers/CarritoController.php`
`/admin/tienda/productos/editar/4`	`plugins/tienda/src/Controllers/Admin/ProductosController.php` → `editar(4)`
`/tienda/js/carrito.js`	o arquivo `plugins/tienda/webroot/js/carrito.js`

Os templates são procurados em plugins/tienda/webroot/templates/<front|admin>/, e os widgets do plugin são usados com {html_widget type="plugins.tienda.front.carrito"}.

Permissões

<?php
// plugins/tienda/config/permissions.php
$PERMISSIONS = [
    'rules' => [
        'tienda'           => ['name' => 'Acesso à loja',        'attributes' => 15],
        'tienda_productos' => ['name' => 'Cadastro de produtos', 'attributes' => 15],
    ],
    'roles' => [
        'Tienda' => 0,
    ],
    'rules_roles' => [
        'Tienda' => [
            'tienda'           => 8,    // só ver
            'tienda_productos' => 15,   // tudo
        ],
    ],
];

attributes são as permissões que a regra admite (bits de add=1, edit=2, delete=4, view=8; veja Segurança). Regras e papéis são criados ou atualizados automaticamente quando o arquivo muda.

<?php
// plugins/tienda/config/menu.php
$MENU = [
    'tienda' => [
        'rules'    => 'tienda',
        'text'     => __('main', [], 'menu', 'tienda'),
        'iconmenu' => 'fa fa-shopping-cart',
        'link'     => Koshkil::getLink('admin/tienda/index'),
        'options'  => [
            'productos' => [
                'text'  => __('products', [], 'menu', 'tienda'),
                'rules' => 'tienda&tienda_productos',
                'link'  => Koshkil::getLink('admin/tienda/productos/listado'),
            ],
        ],
    ],
];

Cada item é exibido somente a quem cumpre roles ou rules.

Reescrita

<?php
// plugins/tienda/config/rewrite.php
$RULES = [
    ['rule' => '^tienda/producto/([0-9]+)$', 'target' => '/tienda/productos/ver/$1', 'flags' => 'L,NC'],
];

Também há uma versão por domínio: config/domains/<domínio>/rewrite.php.

Modelos e extensão de usuários

Koshkil::UsesModel('tienda.productos');     // plugins/tienda/src/Models/productos.php -> TMProductos

Se o plugin define um comportamento usuarios (classe TiendaUsuariosBehavior em plugins/tienda/src/Models/Behaviors/Usuarios.php), ele é anexado automaticamente ao modelo de usuários: é assim que um plugin adiciona métodos como $usuario->pedidos() sem mexer no núcleo. Nos plugins, a classe de um comportamento leva o nome do plugin como prefixo.

Integração com templates

Um tema pode incluir as peças fornecidas por todos os plugins ativos:

{include_plugins folder="admin/dashboard"}              {* cada plugin/webroot/templates/admin/dashboard/*.tpl *}
{include_plugins_scripts file="admin/dashboard.js"}