Conn2Flow
Docs
Navegação das docs

Referência / Bibliotecas

Biblioteca plugins-installer.php

Instala e atualiza um plugin: obtém o pacote (upload, GitHub público ou privado, pasta local), confere SHA-256 e manifesto, move para plugins/<slug>/, roda migrações e sincroniza os dados.

Caminho no Gestor bibliotecas/plugins-installer.php

O motor de instalação de plugins. Quem o chama é o módulo admin-plugins (tela de plugins) e o script de linha de comando gestor/controladores/plugins/atualizacao-plugin.php. Os códigos de saída e estados estão em plugins-consts.php.

Ao ser incluída, carrega também banco.php, plugins-consts.php e o controlador do módulo admin-plugins.

plugin_process(array $params): int

$codigo = plugin_process([
    'slug' => 'meu-plugin',
    'origem_tipo' => 'github_privado',     // upload | github_publico | github_privado | local_path
    'owner' => 'empresa', 'repo' => 'meu-plugin', 'ref' => 'main',
    'cred_ref' => 'EMPRESA',               // lê PLUGIN_TOKEN_EMPRESA do .env
]);
echo plg_exit_code_label($codigo);

Na ordem:

  1. Obter o pacote em sys_get_temp_dir()/plg_<slug>.zip:

    • upload: copia arquivo;

    • github_publico / github_privado: baixa o zip de owner/repo@ref, ou uma download_url direta (asset de release); o privado usa um token (cred_ref);

    • local_path: compacta uma pasta local ou copia um zip pronto.

  2. SHA-256 (só quando há sha256_url): baixa <pacote>.sha256 e compara com o hash do zip. O arquivo precisa conter só o hash; o formato do sha256sum (hash nome) é recusado. Sem sha256_url, não há verificação de integridade.

  3. Checksum inalterado: se o SHA-256 do zip é o mesmo já registrado para o plugin, para aqui com sucesso (use reprocessar para forçar).

  4. Extrair em gestor/temp/plugins/<slug>/ e localizar manifest.json (na raiz ou em plugin/).

  5. Validar o manifesto: id, name e version obrigatórios; version no formato x.y.z; id com minúsculas, dígitos, - e _.

  6. Mover para gestor/plugins/<slug>/ (com backup do anterior).

  7. Migrações Phinx de db/migrations/ do plugin, com a configuração do core.

  8. Dados: os db/data/*Data.json do plugin vão para o banco pelo atualizador de plugins (controladores/plugins/atualizacao-plugin-banco-de-dados.php), com os recursos dos módulos do plugin.

  9. Metadados na tabela plugins (versão, checksum, origem, status_execucao) e log em gestor/logs/plugins/.

Opções: dry_run (não move nem grava no banco), no_migrations, only_migrations, only_resources, no_resources, reprocessar, referencia.

Credenciais do GitHub

plugin_credentials_lookup($cred_ref): um valor que começa com ghp_, github_pat_, gho_, ghu_ ou ghs_ é usado como o próprio token; qualquer outro vira a variável PLUGIN_TOKEN_<VALOR> do .env.

Segurança

Instalar um plugin é executar o código dele no servidor: só instale pacotes de origem confiável, e com sha256_url sempre que possível. Além disso, a normalização de nomes com \ (zips feitos no Windows) move arquivos sem conferir se o destino continua dentro da pasta de staging.

Funções de apoio

Caminhos (plugin_base_root(), plugin_staging_path(), plugin_final_path(), plugin_datajson_dest_dir()), arquivos (plugin_safe_mkdir(), plugin_remove_dir(), plugin_read_json(), plugin_compute_checksum(), plugin_fix_temp_file_permissions(), plugin_cleanup_after_install()), download (plugin_http_download(), plugin_github_zip_url(), plugin_download_github_public(), plugin_download_github_private(), plugin_copy_local_path(), plugin_extract_zip(), plugin_locate_manifest()), instalação (plugin_move_to_final(), plugin_backup_existing(), plugin_persist_metadata(), plugin_mark_status(), plugin_checksum_changed(), plugin_log_block(), plugin_normalize_slug(), plugin_validate_manifest(), plugin_is_cli_context()) e dados (plugin_run_migrations(), plugin_sync_datajson(), plugin_sync_datajson_multi(), plugin_sync_resources_granular(), plugin_sync_modules_resources(), plugin_enrich_resource_checksums(), plugin_guess_resource_files(), plugin_delegate_database_operations(), plugin_db_fetch_one(), plugin_upsert_generic(), plugin_upsert_layout(), plugin_upsert_page(), plugin_upsert_component(), plugin_upsert_variable(), plugin_upsert_module(), tabelaFromDataFile()).

Funções

Gerado a partir de gestor/bibliotecas/plugins-installer.php · 44 funções

44 de 44

plugin_normalize_slug

ver no código · linha 30 ↗
plugin_normalize_slug(string $slug): string

Normaliza um slug de plugin para formato seguro.

Parâmetros

$slugstring
Slug original do plugin.

Retorno

string
Slug normalizado (ex: "My-Plugin_123" → "my-plugin_123").

tabelaFromDataFile

ver no código · linha 110 ↗
tabelaFromDataFile(string $file): string

Converte nome de arquivo *Data.json para nome de tabela snake_case.

Parâmetros

$filestring
Nome do arquivo *Data.json.

Retorno

string
Nome da tabela em snake_case.

plugin_read_json

ver no código · linha 134 ↗
plugin_read_json(string $path, array &$errors): ?array

Lê e decodifica um arquivo JSON.

Parâmetros

$pathstring
Caminho do arquivo JSON.
$errorsarray
Array de erros (passado por referência).

Retorno

?array
Dados decodificados ou null em caso de erro.

plugin_validate_manifest

ver no código · linha 154 ↗
plugin_validate_manifest(array $manifest, array &$errors): bool

Valida campos obrigatórios e formato do manifest.json do plugin.

Parâmetros

$manifestarray
Dados do manifest.json decodificados.
$errorsarray
Array de erros (passado por referência).

Retorno

bool
True se válido, false caso contrário.

plugin_http_download

ver no código · linha 206 ↗
plugin_http_download(string $url, string $dest, array $headers, array &$log): bool

Realiza download HTTP de arquivo com suporte a cURL e fallback para streams.

Parâmetros

$urlstring
URL para download.
$deststring
Caminho do arquivo de destino.
$headersarray
Headers HTTP a enviar (formato: ['Header-Name' => 'value']).
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_github_zip_url

ver no código · linha 276 ↗
plugin_github_zip_url(string $owner, string $repo, string $ref): string

Gera URL para download do zipball de um repositório GitHub.

Parâmetros

$ownerstring
Proprietário do repositório (usuário ou organização).
$repostring
Nome do repositório.
$refstring
Referência (branch, tag ou commit SHA).

Retorno

string
URL completa para download do zipball.

plugin_download_github_public

ver no código · linha 296 ↗
plugin_download_github_public(string $owner, string $repo, string $ref, string $destZip, array &$log): bool

Baixa plugin de repositório público do GitHub.

Parâmetros

$ownerstring
Proprietário do repositório.
$repostring
Nome do repositório.
$refstring
Referência (branch/tag/commit).
$destZipstring
Caminho do arquivo ZIP de destino.
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_download_github_private

ver no código · linha 355 ↗
plugin_download_github_private(string $owner, string $repo, string $ref, string $destZip, string $token, array &$log): bool

Baixa plugin de repositório privado do GitHub usando token de autenticação.

Parâmetros

$ownerstring
Proprietário do repositório.
$repostring
Nome do repositório.
$refstring
Referência (branch/tag/commit).
$destZipstring
Caminho do arquivo ZIP de destino.
$tokenstring
Token de autenticação do GitHub.
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_copy_local_path

ver no código · linha 379 ↗
plugin_copy_local_path(string $sourcePath, string $destZip, array &$log): bool

Copia plugin de caminho local (diretório ou arquivo ZIP).

Parâmetros

$sourcePathstring
Caminho local do plugin (diretório ou arquivo ZIP).
$destZipstring
Caminho do arquivo ZIP de destino.
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_extract_zip

ver no código · linha 419 ↗
plugin_extract_zip(string $zipFile, string $destDir, array &$log): bool

Extrai arquivo ZIP para diretório de destino.

Parâmetros

$zipFilestring
Caminho do arquivo ZIP.
$destDirstring
Diretório de destino para extração.
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_locate_manifest

ver no código · linha 457 ↗
plugin_locate_manifest(string $staging, array &$log): ?string

Localiza o arquivo manifest.json dentro do diretório de staging.

Parâmetros

$stagingstring
Diretório de staging extraído.
$logarray
Array de log (passado por referência).

Retorno

?string
Caminho completo do manifest.json ou null se não encontrado.

plugin_move_to_final

ver no código · linha 490 ↗
plugin_move_to_final(string $staging, string $final, array &$log): bool

Move diretório do plugin de staging para localização final.

Parâmetros

$stagingstring
Diretório de staging.
$finalstring
Diretório final de instalação.
$logarray
Array de log (passado por referência).

Retorno

bool
True se sucesso, false em caso de erro.

plugin_persist_metadata

ver no código · linha 555 ↗
plugin_persist_metadata(string $slug, array $manifest, ?string $checksum, string $origemTipo, array $opcoes, array &$log): void

Persiste metadados do plugin na tabela plugins do banco de dados.

Parâmetros

$slugstring
ID único do plugin.
$manifestarray
Dados do manifest.json.
$checksum?string
Hash SHA-256 do pacote.
$origemTipostring
Tipo de origem (github_public, github_private, local).
$opcoesarray
Opções de instalação (referencia, ref, cred_ref).
$logarray
Array de log (passado por referência).

Retorno

void

plugin_backup_existing

ver no código · linha 610 ↗
plugin_backup_existing(string $finalPath, array &$log): void

Cria backup em ZIP da instalação existente do plugin.

Parâmetros

$finalPathstring
Caminho do plugin instalado.
$logarray
Array de log (passado por referência).

Retorno

void

plugin_sync_datajson

ver no código · linha 638 ↗
plugin_sync_datajson(string $staging, string $slug, array &$log): void

Sincroniza arquivos Data.json do plugin com o banco de dados.

Parâmetros

$stagingstring
Diretório de staging do plugin
$slugstring
Identificador único do plugin
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_sync_datajson_multi

ver no código · linha 705 ↗
plugin_sync_datajson_multi(array $filesMap, string $slug, array &$log, string $finalBase): void

Sincroniza dados a partir de arquivos *Data.json detectados dinamicamente.

Parâmetros

$filesMaparray
Mapeamento de nome da tabela para caminho do arquivo Data.json
$slugstring
Identificador único do plugin
$logarray
Referência ao array de log (passado por referência)
$finalBasestring
Caminho base do plugin instalado

Retorno

void

plugin_run_migrations

ver no código · linha 748 ↗
plugin_run_migrations(string $slug, string $finalPath, array &$log, array $opts = []): void

Executa migrações de banco de dados específicas do plugin usando Phinx.

Parâmetros

$slugstring
Identificador único do plugin
$finalPathstring
Caminho final do plugin instalado
$logarray
Referência ao array de log (passado por referência)
$optsarray
Opções de execução:

Retorno

void

plugin_sync_resources_granular

ver no código · linha 794 ↗
plugin_sync_resources_granular(array $resources, string $pluginId, ?string $baseDir, array &$log): void

Sincroniza recursos (layouts, pages, components, variables) de forma granular.

Parâmetros

$resourcesarray
Array de recursos organizados por idioma
$pluginIdstring
Identificador único do plugin
$baseDir?string
Diretório base para buscar arquivos HTML/CSS (opcional)
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_enrich_resource_checksums

ver no código · linha 848 ↗
plugin_enrich_resource_checksums(?string $baseDir, string $tipo, string $id, array &$item, array &$log): void

Enriquece recursos com checksums calculados a partir de arquivos HTML e CSS.

Parâmetros

$baseDir?string
Diretório base para buscar arquivos
$tipostring
Tipo de recurso: 'layouts', 'pages', ou 'components'
$idstring
Identificador do recurso
$itemarray
Referência ao array do item (modificado com checksums)
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_guess_resource_files

ver no código · linha 873 ↗
plugin_guess_resource_files(string $baseDir, string $tipo, string $id): ?array

Tenta localizar automaticamente arquivos HTML e CSS de um recurso.

Parâmetros

$baseDirstring
Diretório base do plugin
$tipostring
Tipo de recurso: 'layouts', 'pages', ou 'components'
$idstring
Identificador do recurso

Retorno

?array
Array com chaves 'html' e/ou 'css', ou null se não encontrado

plugin_sync_modules_resources

ver no código · linha 905 ↗
plugin_sync_modules_resources(string $staging, string $pluginId, array &$log): void

Sincroniza recursos de módulos a partir de arquivos module-id.json.

Parâmetros

$stagingstring
Diretório de staging do plugin
$pluginIdstring
Identificador único do plugin
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_db_fetch_one

ver no código · linha 995 ↗
plugin_db_fetch_one(string $sql): array|null

Busca e retorna um único registro do banco de dados.

Parâmetros

$sqlstring
Consulta SQL completa

Retorno

array|null
Array associativo com os dados ou null se não encontrado

plugin_delegate_database_operations

ver no código · linha 1011 ↗
plugin_delegate_database_operations(string $pluginSlug, array $dataFiles, array &$log): bool

Delega operações de banco de dados para o sistema robusto de atualizações.

Parâmetros

$pluginSlugstring
Slug normalizado do plugin
$dataFilesarray
Lista de arquivos Data.json para processar (vazio = todos)
$logarray
Array de log passado por referência para registrar mensagens

Retorno

bool
True se a delegação foi bem-sucedida, false em caso de erro

plugin_upsert_generic

ver no código · linha 1080 ↗
plugin_upsert_generic(string $tableName, string $pluginSlug, array $row, array &$tot, array &$log): void

Função genérica de upsert que delega para o sistema robusto de banco de dados.

Parâmetros

$tableNamestring
Nome da tabela
$pluginSlugstring
Identificador único do plugin
$rowarray
Dados da linha a ser inserida/atualizada
$totarray
Referência ao array de totalizadores (passado por referência)
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_upsert_layout

ver no código · linha 1103 ↗
plugin_upsert_layout(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza um layout no banco de dados.

Parâmetros

$pluginstring
Identificador do plugin
$langstring
Código do idioma (ex: 'pt-br')
$idstring
Identificador único do layout
$srcarray
Dados source com chaves: name/nome, checksum, version
$totarray
Referência ao array de totalizadores (passado por referência)

Retorno

void

plugin_upsert_page

ver no código · linha 1164 ↗
plugin_upsert_page(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza uma página no banco de dados.

Parâmetros

$pluginstring
Identificador do plugin
$langstring
Código do idioma (ex: 'pt-br')
$idstring
Identificador único da página
$srcarray
Dados source com chaves: name/nome, path/caminho, module/modulo, checksum, version
$totarray
Referência ao array de totalizadores (passado por referência)

Retorno

void

plugin_upsert_component

ver no código · linha 1232 ↗
plugin_upsert_component(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza um componente no banco de dados.

Parâmetros

$pluginstring
Identificador do plugin
$langstring
Código do idioma (ex: 'pt-br')
$idstring
Identificador único do componente
$srcarray
Dados source com chaves: name/nome, module/modulo, checksum, version
$totarray
Referência ao array de totalizadores (passado por referência)

Retorno

void

plugin_upsert_variable

ver no código · linha 1295 ↗
plugin_upsert_variable(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza uma variável no banco de dados.

Parâmetros

$pluginstring
Identificador do plugin
$langstring
Código do idioma (ex: 'pt-br')
$idstring
Identificador único da variável
$srcarray
Dados source com chaves: value/valor, type/tipo, group/grupo, module/modulo
$totarray
Referência ao array de totalizadores (passado por referência)

Retorno

void

plugin_upsert_module

ver no código · linha 1346 ↗
plugin_upsert_module(string $plugin, string $id, array $src, array &$tot): void

Insere ou atualiza um módulo no banco de dados.

Parâmetros

$pluginstring
Identificador do plugin
$idstring
Identificador único do módulo
$srcarray
Dados source com chaves: name/nome, modulo_grupo_id, titulo, icone, icone2,
$totarray
Referência ao array de totalizadores (passado por referência)

Retorno

void

plugin_checksum_changed

ver no código · linha 1402 ↗
plugin_checksum_changed(string $slug, ?string $newChecksum): bool

Verifica se o checksum do pacote mudou desde a última instalação.

Parâmetros

$slugstring
Identificador único do plugin
$newChecksum?string
Novo checksum calculado (SHA-256)

Retorno

bool
True se mudou ou se não há checksum anterior, false se inalterado

plugin_mark_status

ver no código · linha 1424 ↗
plugin_mark_status(string $slug, string $status): void

Marca o status de execução do plugin no banco de dados.

Parâmetros

$slugstring
Identificador único do plugin
$statusstring
Status a ser registrado (ex: 'instalando', 'erro', 'concluído')

Retorno

void

plugin_log_block

ver no código · linha 1440 ↗
plugin_log_block(array $logLines, string $slug): void

Registra mensagens de log em arquivo com timestamp.

Parâmetros

$logLinesarray
Array de mensagens de log
$slugstring
Identificador único do plugin

Retorno

void

plugin_cleanup_after_install

ver no código · linha 1458 ↗
plugin_cleanup_after_install(string $finalPath, array &$log): void

Limpa pasta DB e corrige permissões após instalação do plugin.

Parâmetros

$finalPathstring
Caminho do plugin instalado
$logarray
Referência ao array de log (passado por referência)

Retorno

void

plugin_process

ver no código · linha 1539 ↗
plugin_process(array $params): int

Função principal do instalador de plugins - orquestra todo o processo.

Parâmetros

$paramsarray
Parâmetros da instalação:

Retorno

int
Código de saída:

Verificado contra o código no commit a1a87ec9

Fontes:

O Futuro é Híbrido: Humano + IA.

O Conn2Flow é a ferramenta. Se você precisa do Arquiteto para desenhar a estratégia da sua empresa usando essa tecnologia...

Contrate Consultoria Especializada