VRP - Censimento delle utilities (piattaforma contro servizi)

Misurato il 2026-08-06 su /srv/http/lab. Chiesto da vitti: "verifichiamo che

utilities fornisce la piattaforma e usiamo quelle in tutti i servizi; rileggiamo

i codici dei servizi e mettiamo nella piattaforma tutte le utilities che possono

essere utilizzate".

Regola che ne esce, e che vale da qui in avanti:

**la doc generata e' il riferimento. Se nel codice c'e' qualcosa di diverso, e'

il codice a essere sbagliato.** La doc si rigenera con php docs/genera_doc.php.

1. Stato della documentazione (misurato, non ricordato)

ramo	funzioni PHP	con commento `/** */`	in `VRP_API_lib.md`
piattaforma (`platform/lib`)	111	110 (99%)	110 = tutte
wizard (`public/wiz_foto`)	89	39 (44%)	38
VRV (`public/vv/lib` + `inc`)	249	55 (22%)	51

La piattaforma e' a posto: quello che offre e' scritto. Il VRV no: **quattro

funzioni su cinque non hanno il commento**, quindi non entrano nella doc e

nessuno sa che esistono - per questo si riscrivono in casa.

Rigenerata il 06/08: nessuna funzione nuova, nessun fantasma (il diff dei titoli

e' vuoto). Backup della precedente in quarantena_bak/20260806_passo1/.

2. Cosa offre gia' la piattaforma (le vrp_*, ~50)

Ambiente: boot/vrp_defines.php + boot/env.json -> VRP_APP_NAME,

VRP_CHANNEL, VRP_BASE_URL, VRP_DEBUG, VRP_HOST, VRP_TZ, VRP_LOG_LEVEL,

VRP_LOG_FILE, VRP_SESSION_TTL, VRP_SHARED_DIR, VRP_MEDIA_ROOT, VRP_MEDIA_URL,

VRP_DB_CREDS, VRP_SERVICES.

Database: vrp_db, vrp_run, vrp_val, vrp_row, vrp_all, vrp_insert.
Log: vrp_log_trace/debug/info/warn/error, vrp_log_write, vrp_log_enabled.
Identita' e permessi: vrp_current_user, vrp_user_role, vrp_is_admin,

vrp_role_top, vrp_role_icon, vrp_login, vrp_logout, vrp_session_check,

vrp_guard_request, vrp_csrf_token, vrp_csrf_check, vrp_visit_check.

Uso quotidiano: vrp_h (escape), vrp_url, vrp_asset_url (cache-buster),

vrp_load_json, vrp_is_lan, vrp_client_ip.

Attrezzi grossi: vrp_explorer_* (l'esploratore riusabile), vrp_img_*

(immagini servite al volo), vrp_services, vrp_service_config.

3. I mestieri rifatti in casa (i doppioni veri)

mestiere	piattaforma	il VRV/VRW fa invece	numeri
escape HTML	`vrp_h()`	`h()` definita 5 volte (lib/helper, core/3_2_1_Go, lib/header_badge, + 5 nel wizard)	123 usi di h(), 172 htmlspecialchars a mano, 148 vrp_h
log	`vrp_log_*`	`log_info/warn/error/trace/debug` definite due volte (functions.php e 3_2_1_Go.php)	217 usi nel VRV contro 16 di vrp_log
database	`vrp_db` + run/val/row/all/insert	`lib/db_utilities.php` (11) + `lib/db_polyfills.php` (6), con `db_exec/db_insert/db_select_row` doppie	2 connessioni PDO separate
ambiente	`vrp_defines.php`	`lib/core/meta.php` (ripulito il 06/08)	33 costanti in doppio

Regola pratica da qui in avanti: prima di scrivere una funzione, cercarla in

VRP_API_lib.md. Se serve a piu' di un servizio, nasce in platform/lib col

prefisso vrp_ e col commento /** @desc @param @return */.

4. Candidate a SALIRE in piattaforma (oggi sono di un servizio solo)

Vivono in platform/lib/vrs.php o vrw.php (lib di servizio) ma il mestiere e'

di tutti:

vrs_format_bytes (dimensioni in parole)
vrs_sanitize_filename, vrs_sanitize_dirname (nomi file sicuri)
vrs_is_thumbable, vrs_is_video / vrw_is_jpeg, vrw_is_heic, vrw_is_video

(riconoscimento tipo file: **oggi sono due famiglie che rispondono alla stessa

domanda**)

vrw_exif_date, vrw_video_date, vrw_filename_date (data di scatto)
vrw_heic_to_jpg, vrw_mkdir, vrw_safe_target_path

5. Il VRV: quanto codice e' davvero vivo

219 funzioni PHP distinte (273 dichiarazioni: 40 nomi sono dichiarati piu'

di una volta). Attenzione: il conto a occhio col grep ne dava 329, ma dentro i

PHP c'e' anche il JavaScript - vedi sotto.

52 non sono chiamate da nessun PHP di tutto il lab (elenco in

scratchpad/vrv_mai_chiamate.txt). Fra queste: vv_selftest, vv_meta_debug,

vv_compile_version, draft_get/draft_delete, can_edit_post e i suoi due

gemelli, puo'_visualizzare_post (col nome accentato).

NON cancellare a scatola chiusa: alcune sono attrezzi da riga di comando.

10 file esistono in due copie, in vv/ e in vv/lib/: audio.php,

auth.php, guard_admin.php, ridimensiona_funziona.php, ridimensiona_lib.php

(IDENTICI) e colors.php, db_utilities.php, footer.php,

header_badge_mini.php, trad_widget.php (DIVERSI: quale vince dipende da

chi fa il require).

JavaScript dentro i PHP

Domanda di vitti: "ma non stavano in file dentro js/?". Misurato:

in js/: 16 file, 4.482 righe
dentro i PHP, nei blocchi <script>: 127 funzioni, 3.633 righe - cioe'

quasi la meta' del JavaScript del VRV non sta in un file .js.

I piu' pesanti: lib/caricaTinyMCE.php (1.590 righe di JS, 49 funzioni),

media_popup.php (323), diario_lista_admin.php (215),

lib/header_badge.php (205), visualizza_post_draft.php (171).

Conseguenze pratiche: quel codice non e' documentabile (la sezione JavaScript

della doc pesca solo dai .js), non si mette in cache, e non si puo' provare da

solo. Candidati allo scorporo, in quest'ordine: caricaTinyMCE, media_popup,

header_badge.