Biblioteca assets-externos.php

Caminho no Gestor bibliotecas/assets-externos.php

Todo JavaScript e CSS de terceiros que o Gestor usa passa por um registro único, com a versão fixada. Um módulo não escreve a tag: pede assets_externos_incluir('codemirror').

O arquivo é servido de gestor/assets/vendor/<biblioteca>/<versão>/ quando existe, e do CDN do registro quando não existe. Assim o IP do visitante não vai para CDNs de terceiros, e uma publicação nova no npm não entra em produção sem revisão.

Bibliotecas registradas

Os arquivos das instalações novas já vêm em gestor/assets/vendor/. Para baixar o que faltar (ou uma versão nova depois de mudar o registro):

c2f assets:vendor [--lib=codemirror] [--listar] [--forcar]

A entrada arquivos de uma biblioteca lista o que é baixado mas não vira tag (as fontes que o CSS pede por caminho relativo). Sem elas, servido do disco, o Fomantic fica sem ícones.

Uso

gestor_incluir_biblioteca('assets-externos');
assets_externos_incluir('sortablejs');                  // false se o nome não está registrado
$tags = assets_externos_tags('quill', $vendorFisico, $vendorPublico);   // ['css' => [...], 'js' => [...]]
$mapa = assets_externos_urls_js(['codemirror']);        // biblioteca => arquivo => URL, para o JavaScript

assets_externos_urls_js() existe para o que monta tags no navegador (os iframe de pré-visualização e a barra de edição): recebem as mesmas URLs, sem conhecer versão nem host.

Armadilhas

• A troca para o CDN é silenciosa: um arquivo ausente em vendor/ sai do CDN sem aviso. Depois de mudar uma versão, rode c2f assets:vendor.

• assets_externos_incluir() põe as tags de CSS pela gestor_pagina_css_incluir($tag), que as empilha na fila de JavaScript do fim da página (gestor.php). O CSS funciona, mas carrega depois do conteúdo.

• A URL local usa url-raiz, que inclui o prefixo de idioma quando ele está na URL.

Auxiliares internos (usados pelas funções acima; raramente chamados direto): assets_externos_registro(), assets_externos_url(), assets_externos_urls_map().

Funções

assets_externos_registro(): array<string, array{versao: string, cdn: string, css: list<string>, js: list<string>}>

assets_externos_url(array $lib, string $nome, string $arquivo, string $vendorFisico, string $vendorPublico): string

assets_externos_tags(string $nome, string $vendorFisico = '', string $vendorPublico = ''): array{css: list<string>, js: list<string>}

assets_externos_urls_map(list<string> $nomes = Array(), string $vendorFisico = '', string $vendorPublico = ''): array<string, array<string, string>>

assets_externos_urls_js(list<string> $nomes = Array()): array<string, array<string, string>>

assets_externos_incluir(string $nome): bool