Conn2Flow
Docs
Docs navigation

Reference / Libraries

plugins-installer.php library

Installs and updates a plugin: fetches the package (upload, public or private GitHub, local folder), checks SHA-256 and the manifest, moves it to plugins/<slug>/, runs migrations and syncs the data.

Path in the Gestor bibliotecas/plugins-installer.php

The plugin installation engine. It is called by the admin-plugins module (plugins screen) and by the gestor/controladores/plugins/atualizacao-plugin.php command-line script. Exit codes and states are in plugins-consts.php.

When included, it also loads banco.php, plugins-consts.php and the admin-plugins module controller.

plugin_process(array $params): int

$code = plugin_process([
    'slug' => 'my-plugin',
    'origem_tipo' => 'github_privado',     // upload | github_publico | github_privado | local_path
    'owner' => 'company', 'repo' => 'my-plugin', 'ref' => 'main',
    'cred_ref' => 'COMPANY',               // reads PLUGIN_TOKEN_COMPANY from the .env
]);
echo plg_exit_code_label($code);

In order:

  1. Fetch the package into sys_get_temp_dir()/plg_<slug>.zip:

    • upload: copies arquivo;

    • github_publico / github_privado: downloads the zip of owner/repo@ref, or a direct download_url (release asset); the private one uses a token (cred_ref);

    • local_path: zips a local folder or copies a ready zip.

  2. SHA-256 (only when there is a sha256_url): downloads <package>.sha256 and compares it with the zip hash. The file must contain only the hash; the sha256sum format (hash name) is rejected. Without sha256_url, there is no integrity check.

  3. Unchanged checksum: if the zip SHA-256 equals the one already recorded for the plugin, it stops here successfully (use reprocessar to force).

  4. Extract into gestor/temp/plugins/<slug>/ and locate manifest.json (at the root or in plugin/).

  5. Validate the manifest: id, name and version required; version as x.y.z; id with lowercase letters, digits, - and _.

  6. Move to gestor/plugins/<slug>/ (backing up the previous one).

  7. Migrations: the plugin's Phinx db/migrations/, with the core configuration.

  8. Data: the plugin's db/data/*Data.json go to the database through the plugin updater (controladores/plugins/atualizacao-plugin-banco-de-dados.php), with the resources of the plugin's modules.

  9. Metadata in the plugins table (version, checksum, origin, status_execucao) and a log in gestor/logs/plugins/.

Options: dry_run (neither moves nor writes to the database), no_migrations, only_migrations, only_resources, no_resources, reprocessar, referencia.

GitHub credentials

plugin_credentials_lookup($cred_ref): a value starting with ghp_, github_pat_, gho_, ghu_ or ghs_ is used as the token itself; anything else becomes the PLUGIN_TOKEN_<VALUE> variable of the .env.

Security

Installing a plugin means running its code on the server: only install packages from trusted sources, and with sha256_url whenever possible. Also, the normalization of names containing \ (zips made on Windows) moves files without checking that the target stays inside the staging folder.

Support functions

Paths (plugin_base_root(), plugin_staging_path(), plugin_final_path(), plugin_datajson_dest_dir()), files (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()), installation (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()) and data (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()).

Functions

Generated from gestor/bibliotecas/plugins-installer.php · 44 functions

44 of 44

plugin_normalize_slug

view source · line 30 ↗
plugin_normalize_slug(string $slug): string

Normaliza um slug de plugin para formato seguro.

Parameters

$slugstring
Slug original do plugin.

Returns

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

plugin_staging_path

view source · line 45 ↗
plugin_staging_path(string $slug): string

Retorna o caminho de staging temporário para um plugin.

Parameters

$slugstring
Slug do plugin.

Returns

string
Caminho completo para temp/plugins/{slug}.

plugin_final_path

view source · line 53 ↗
plugin_final_path(string $slug): string

Retorna o caminho final de instalação de um plugin.

Parameters

$slugstring
Slug do plugin.

Returns

string
Caminho completo para plugins/{slug}.

plugin_datajson_dest_dir

view source · line 61 ↗
plugin_datajson_dest_dir(string $slug): string

Retorna o diretório de destino para arquivos *Data.json do plugin.

Parameters

$slugstring
Slug do plugin.

Returns

string
Caminho completo para db/data/plugins/{slug}.

tabelaFromDataFile

view source · line 110 ↗
tabelaFromDataFile(string $file): string

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

Parameters

$filestring
Nome do arquivo *Data.json.

Returns

string
Nome da tabela em snake_case.

plugin_read_json

view source · line 134 ↗
plugin_read_json(string $path, array &$errors): ?array

Lê e decodifica um arquivo JSON.

Parameters

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

Returns

?array
Dados decodificados ou null em caso de erro.

plugin_validate_manifest

view source · line 154 ↗
plugin_validate_manifest(array $manifest, array &$errors): bool

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

Parameters

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

Returns

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

plugin_credentials_lookup

view source · line 173 ↗
plugin_credentials_lookup(?string $credRef): ?string

Busca credenciais de token para acesso a repositórios privados.

Parameters

$credRef?string
Referência ou token direto.

Returns

?string
Token encontrado ou null.

plugin_http_download

view source · line 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.

Parameters

$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).

Returns

bool
True se sucesso, false em caso de erro.

plugin_github_zip_url

view source · line 276 ↗
plugin_github_zip_url(string $owner, string $repo, string $ref): string

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

Parameters

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

Returns

string
URL completa para download do zipball.

plugin_download_github_public

view source · line 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.

Parameters

$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).

Returns

bool
True se sucesso, false em caso de erro.

plugin_download_github_private

view source · line 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.

Parameters

$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).

Returns

bool
True se sucesso, false em caso de erro.

plugin_copy_local_path

view source · line 379 ↗
plugin_copy_local_path(string $sourcePath, string $destZip, array &$log): bool

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

Parameters

$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).

Returns

bool
True se sucesso, false em caso de erro.

plugin_extract_zip

view source · line 419 ↗
plugin_extract_zip(string $zipFile, string $destDir, array &$log): bool

Extrai arquivo ZIP para diretório de destino.

Parameters

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

Returns

bool
True se sucesso, false em caso de erro.

plugin_locate_manifest

view source · line 457 ↗
plugin_locate_manifest(string $staging, array &$log): ?string

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

Parameters

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

Returns

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

plugin_move_to_final

view source · line 490 ↗
plugin_move_to_final(string $staging, string $final, array &$log): bool

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

Parameters

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

Returns

bool
True se sucesso, false em caso de erro.

plugin_persist_metadata

view source · line 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.

Parameters

$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).

Returns

void

plugin_backup_existing

view source · line 610 ↗
plugin_backup_existing(string $finalPath, array &$log): void

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

Parameters

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

Returns

void

plugin_sync_datajson

view source · line 638 ↗
plugin_sync_datajson(string $staging, string $slug, array &$log): void

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

Parameters

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

Returns

void

plugin_sync_datajson_multi

view source · line 705 ↗
plugin_sync_datajson_multi(array $filesMap, string $slug, array &$log, string $finalBase): void

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

Parameters

$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

Returns

void

plugin_run_migrations

view source · line 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.

Parameters

$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:

Returns

void

plugin_sync_resources_granular

view source · line 794 ↗
plugin_sync_resources_granular(array $resources, string $pluginId, ?string $baseDir, array &$log): void

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

Parameters

$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)

Returns

void

plugin_enrich_resource_checksums

view source · line 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.

Parameters

$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)

Returns

void

plugin_guess_resource_files

view source · line 873 ↗
plugin_guess_resource_files(string $baseDir, string $tipo, string $id): ?array

Tenta localizar automaticamente arquivos HTML e CSS de um recurso.

Parameters

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

Returns

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

plugin_sync_modules_resources

view source · line 905 ↗
plugin_sync_modules_resources(string $staging, string $pluginId, array &$log): void

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

Parameters

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

Returns

void

plugin_db_fetch_one

view source · line 995 ↗
plugin_db_fetch_one(string $sql): array|null

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

Parameters

$sqlstring
Consulta SQL completa

Returns

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

plugin_delegate_database_operations

view source · line 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.

Parameters

$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

Returns

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

plugin_upsert_generic

view source · line 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.

Parameters

$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)

Returns

void

plugin_upsert_layout

view source · line 1103 ↗
plugin_upsert_layout(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza um layout no banco de dados.

Parameters

$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)

Returns

void

plugin_upsert_page

view source · line 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.

Parameters

$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)

Returns

void

plugin_upsert_component

view source · line 1232 ↗
plugin_upsert_component(string $plugin, string $lang, string $id, array $src, array &$tot): void

Insere ou atualiza um componente no banco de dados.

Parameters

$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)

Returns

void

plugin_upsert_variable

view source · line 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.

Parameters

$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)

Returns

void

plugin_upsert_module

view source · line 1346 ↗
plugin_upsert_module(string $plugin, string $id, array $src, array &$tot): void

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

Parameters

$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)

Returns

void

plugin_checksum_changed

view source · line 1402 ↗
plugin_checksum_changed(string $slug, ?string $newChecksum): bool

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

Parameters

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

Returns

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

plugin_mark_status

view source · line 1424 ↗
plugin_mark_status(string $slug, string $status): void

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

Parameters

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

Returns

void

plugin_log_block

view source · line 1440 ↗
plugin_log_block(array $logLines, string $slug): void

Registra mensagens de log em arquivo com timestamp.

Parameters

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

Returns

void

plugin_cleanup_after_install

view source · line 1458 ↗
plugin_cleanup_after_install(string $finalPath, array &$log): void

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

Parameters

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

Returns

void

plugin_fix_temp_file_permissions

view source · line 1479 ↗
plugin_fix_temp_file_permissions(string $filePath, array &$log): void

Corrige permissões de arquivo temporário via chown.

Parameters

$filePathstring
Caminho completo do arquivo
$logarray
Referência ao array de log (passado por referência)

Returns

void

plugin_process

view source · line 1539 ↗
plugin_process(array $params): int

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

Parameters

$paramsarray
Parâmetros da instalação:

Returns

int
Código de saída:

Verified against the code at commit a1a87ec9

Sources:

The Future is Hybrid: Human + AI.

Conn2Flow is the tool. If you need the Architect to design your company's strategy using this technology...

Hire Specialized Consulting