Documentació

0. Descripció, propòsit i entorn actual

Descripció general i propòsit

Gestió de Monedes és una aplicació web desenvolupada en PHP pur per registrar, consultar, editar, filtrar, importar i exportar una col·lecció de monedes. El propòsit principal del projecte és oferir una eina simple però completa per gestionar catàlegs numismàtics en un entorn acadèmic o personal sense dependre de frameworks externs.

El projecte resol tres necessitats concretes: mantenir una col·lecció ordenada, facilitar la consulta ràpida de dades i permetre la interoperabilitat amb altres eines mitjançant fitxers XML i CSV. La interfície està pensada perquè un usuari no tècnic pugui treballar-hi amb fluïdesa des del navegador.

Visió general del sistema

flowchart TD
    APP["App principal\nGestió de Monedes"]
    CMS["CMS\nWordPress · MediaWiki · Joomla"]
    DB[("MariaDB")]
    FD[/"XML / CSV"/]

    APP -->|"PDO"| DB
    CMS -->|"PDO"| DB
    APP -.->|"Exporta"| FD
    CMS -.->|"Importa / exporta"| FD
        

Diagrama de propòsit i abast

flowchart TD
    U(["Usuari/ària"])
    F["CRUD · filtres · imatges\nimportació i exportació"]
    APP["Gestió de Monedes"]
    BD[("MariaDB")]
    U --> F
    F --> APP
    APP -->|PDO| BD
        

Entorn actual

Millores aplicades a la revisió general

• Configuració central més robusta: APP_URL auto-detectada, suport per variables d'entorn i mode debug controlat.
• Sessió i CSRF desacoblats de les vistes mitjançant helpers globals reutilitzables.
• Validació d'imatges més estricta amb MIME real, comprovació d'imatge vàlida i protecció automàtica del directori uploads/.
• Correcció del problema d'imatges òrfenes quan una validació o una escriptura a BD fallava després de la pujada.
• Edició millorada: ara es pot eliminar la imatge actual sense haver de pujar-ne una de nova.
• Importació/exportació reforçada: validació de mida/extensió/MIME, XML amb LIBXML_NONET, CSV amb capçalera validada i exportacions protegides amb CSRF.
• Millora d'UX al formulari: drag&drop real, previsualització coherent i missatges més ajustats a la configuració real.
• Redisseny visual complet: paleta més clara, contrast més net, superfícies més llegibles i coherència entre targetes, formularis i navegació.
• Documentació refeta visualment: llistes amb marques, espaiat corregit, blocs de codi llegibles i contingut alineat amb el desplegament real.

1. Planificació del sistema

Gestió de Monedes és una aplicació web desenvolupada en PHP pur (sense frameworks) que permet gestionar una col·lecció de monedes de curs legal, tant actuals com històriques. Utilitza MariaDB com a sistema de gestió de base de dades relacional i segueix el patró arquitectònic MVC (Model-Vista-Controlador).

Fases de planificació del projecte

La planificació s'ha estructurat en fases petites i acumulatives per garantir un resultat funcional des de les primeres iteracions i poder ampliar el projecte amb millores sense reescriure la base.

flowchart TD
    F1["Fase 1\nAnàlisi del problema"] --> F2["Fase 2\nModel de dades"]
    F2 --> F3["Fase 3\nDesenvolupament CRUD"]
    F3 --> F4["Fase 4\nFuncionalitats avançades"]
    F4 --> F5["Fase 5\nDesplegament i documentació"]
    style F1 fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    style F2 fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    style F3 fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    style F4 fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    style F5 fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
        

Arquitectura MVC

El projecte està organitzat en tres capes ben diferenciades:

flowchart TB
    V1["Vistes\nheader · llistat · formulari · detall"]
    C1["Controladors\nindex.php · MonedaController · ImportExportController"]
    M1["Models\nMoneda.php · GestorImatge.php"]
    BD[("MariaDB\ngestio_monedes · taula monedes")]
    V1 <-->|"HTML renderitzat"| C1
    C1 <-->|"Crida al model"| M1
    M1 <-->|"PDO"| BD
        

Flux de dades

flowchart TD
    HTTP(["Petició HTTP GET/POST"])
    Router["index.php · enrutador"]
    ACCIO["Acció seleccionada\ncrear · editar · veure · eliminar · llistat"]
    M["Moneda + GestorImatge"]
    BD[("MariaDB\ntaula monedes")]
    V["Vista HTML"]
    HTTP --> Router
    Router --> ACCIO
    ACCIO --> M
    M -->|"PDO singleton"| BD
    M --> V
    V --> Res(["Resposta al navegador"])
        

Esquema de base de dades

La base de dades consta d'una taula principal normalitzada:

Índexs creats per optimitzar les consultes:

• idx_nom — Cerca per nom
• idx_pais — Filtre per país
• idx_any_emissio — Filtre per any
• idx_valor — Filtre per valor

2. Manual d'usuari

Aquesta secció explica com fer servir l'aplicació des del navegador i actua com a manual d'usuari web del projecte. A més, el mateix manual també s'ha publicat en format wiki a MediaWiki i en formats PDF i DOCX descarregables.

2.0 Manual en format wiki, PDF i DOCX

2.1 Gestió de monedes (CRUD)

Afegir una nova moneda

1. Fes clic a «Nova moneda» a la barra de navegació superior o al botó del llistat.
2. Omple els camps del formulari:
   • Nom (obligatori): nom oficial o popular (ex: «Euro», «Pesseta», «Denari»).
   • País (obligatori): territori emissor (ex: «Espanya», «Unió Europea»).
   • Valor (obligatori): valor facial o numismàtic en format numèric (ex: 1.00, 0.50).
   • Any (obligatori): any d'emissió. Per anys a.C., utilitza valors negatius (ex: -264).
   • Descripció (opcional): informació addicional sobre la moneda.
   • Imatge (opcional): foto de la moneda (JPG, PNG, GIF o WebP, màx. 5 MB).
3. Fes clic a «Crear moneda».
4. L'aplicació mostrarà un missatge de confirmació i tornarà al llistat.

Consultar i veure monedes

La pàgina principal mostra totes les monedes en format de targetes. Pots:

• Fer clic sobre la imatge o el nom per veure el detall complet.
• Ordenar el llistat fent clic a Nom, Any o Valor.
• Navegar per les pàgines si la col·lecció té més de 12 elements.

Editar una moneda

1. A la targeta de la moneda, fes clic al botó «Editar».
2. Modifica els camps que vulguis. Si no selecciones una nova imatge, la imatge actual es conserva.
3. Fes clic a «Desar canvis».

Eliminar una moneda

1. Fes clic al botó «Eliminar» (vermell) a la targeta o a la vista de detall.
2. Apareixerà una finestra de confirmació. Revisa el nom de la moneda.
3. Fes clic a «Eliminar» per confirmar, o «Cancel·lar» per abortar.
4. ⚠️ Aquesta acció és permanent i elimina també la imatge del servidor.

2.2 Cerca i filtres

El panell de filtres es troba a la part superior del llistat. Pots combinar qualsevol dels filtres disponibles:

Per esborrar tots els filtres, fes clic al botó × que apareix quan hi ha filtres actius, o al link «Mostra-les totes».

2.3 Gestió d'imatges

• Formats admesos: JPG, JPEG, PNG, GIF, WebP.
• Mida màxima: 5 MB.
• Pots arrossegar la imatge directament sobre la zona de pujada (drag & drop).
• Es mostra una previsualització en temps real abans de desar.
• Les imatges s'emmagatzemen al directori uploads/ del servidor.
• En eliminar una moneda, la seva imatge s'elimina automàticament del servidor.

2.4 Importació i Exportació

Exportar (XML i CSV)

1. Ves a «Import/Export» a la navegació superior.
2. Fes clic a «Descarregar XML» o «Descarregar CSV».
3. El navegador descarregarà el fitxer automàticament amb el nom monedes_YYYYMMDD_HHMMSS.xml/csv.

Importar XML

1. Prepara el fitxer XML amb l'estructura correcta (mostrada a la pàgina).
2. Selecciona el fitxer i fes clic a «Importar des de XML».
3. L'aplicació processarà el fitxer i mostrarà quantes monedes s'han importat.

Importar CSV

1. Prepara el fitxer CSV amb la capçalera: nom;país;valor;any emissió;descripció.
2. Selecciona el fitxer i fes clic a «Importar des de CSV».
3. El sistema detecta automàticament el separador (punt i coma o coma).

Compatibilitat

WordPress MediaWiki Joomla

• WordPress: l'XML és importable via plugins com WP All Import.
• Joomla: estructura compatible amb l'importador de continguts.
• MediaWiki: l'XML es pot processar amb bots per crear/actualitzar articles.

3. Guia d'instal·lació, configuració i dependències

3.1 Requisits del sistema

3.2 Dependències necessàries i com resoldre-les

Per desplegar l'aplicació cal disposar d'un entorn web PHP amb connexió a MariaDB i amb les extensions adequades. La taula següent resumeix les dependències mínimes, el paquet habitual i la forma de verificar-les.

Després d'instal·lar o corregir dependències, reinicia el servidor web perquè PHP carregui els mòduls nous i comprova novament les ordres de verificació.

3.3 Instal·lació de MariaDB

sudo apt update
sudo apt install mariadb-server mariadb-client -y
sudo systemctl start mariadb
sudo systemctl enable mariadb

sudo mysql_secure_installation
# Respon les preguntes:
# - Canviar contrasenya de root: s (o n si és local)
# - Eliminar usuaris anònims: s
# - Desactivar login remot de root: s
# - Eliminar base de dades de prova: s
# - Recarregar privilegis: s

mysql -u root -p
# Introdueix la contrasenya
# Ha de mostrar el prompt: MariaDB [(none)]>
exit;

3.4 Configuració de PHP

sudo apt install php php-mysql php-mbstring php-fileinfo php-xml -y
# Verificar la versió
php -v

# Localitzar el fitxer php.ini
php --ini | grep "Loaded Configuration"

# Editar els valors:
file_uploads = On
upload_max_filesize = 10M
post_max_size = 12M
max_execution_time = 60

sudo systemctl restart apache2
# o
sudo systemctl restart nginx

3.5 Configuració del projecte

# Copiar el projecte al directori web
cp -r gestio_monedes/ /var/www/html/
# o en local amb XAMPP:
cp -r gestio_monedes/ /opt/lampp/htdocs/

// Opció A: editar config.php amb els valors necessaris
define('DB_HOST',  'localhost');
define('DB_NAME',  'gestio_monedes');
define('DB_USER',  'gestio_monedes_app');
define('DB_PASS',  '********');

// APP_URL es detecta sola, però es pot sobreescriure:
export GESTIO_MONEDES_APP_URL="https://exemple.com/gestio_monedes"

// Opció B: usar variables d'entorn
export GESTIO_MONEDES_DB_HOST="localhost"
export GESTIO_MONEDES_DB_NAME="gestio_monedes"
export GESTIO_MONEDES_DB_USER="gestio_monedes_app"
export GESTIO_MONEDES_DB_PASS="********"
export GESTIO_MONEDES_APP_DEBUG="0"

/etc/gestio_monedes/config.local.php

mkdir -p /var/www/html/gestio_monedes/uploads
chmod 755 /var/www/html/gestio_monedes/uploads
chown www-data:www-data /var/www/html/gestio_monedes/uploads

3.6 Resolució d'errors comuns

Comandaments útils de verificació

# Verificar que les extensions PHP estan actives
php -m | grep -E "pdo|mysql|mbstring|fileinfo"

# Comprovar que MariaDB escolta al port correcte
sudo netstat -tlnp | grep 3306

# Verificar els logs de PHP
tail -f /var/log/php_errors.log

# Testar la connexió a la BD directament amb l'usuari de l'aplicació
MYSQL_PWD='********' mariadb -u gestio_monedes_app -e "SHOW DATABASES LIKE 'gestio_monedes';"

# Comprovar sintaxi dels fitxers PHP principals
find /var/www/html/gestio_monedes -name '*.php' -print0 | xargs -0 -n1 php -l

4. Extensió per a WordPress

4.1 Objectiu de l'extensió

El projecte incorpora una extensió específica per a WordPress anomenada Gestio Monedes WP. Aquesta extensió permet reutilitzar el catàleg de monedes dins d'un lloc WordPress sense reescriure la lògica de negoci de l'aplicació principal.

La seva funció és actuar com a connector entre WordPress i les dades del projecte, de manera que el catàleg es pugui mostrar en una pàgina o entrada i es pugui alimentar des de diferents fonts: MariaDB, CSV o XML. La versió actual també reforça l'experiència d'ús amb diagnòstic visual de les fonts, controls de consulta més rics i un frontend molt més alineat amb la resta del projecte, amb amplada ampla dins del tema i una capçalera introductòria centrada perquè el catàleg no quedi encaixonat visualment.

4.2 Funcionalitats implementades

• Llegeix informació de la base de dades MariaDB del projecte.
• Llegeix informació des d'un arxiu CSV extern.
• Llegeix informació des d'un arxiu XML extern.
• Permet inserir noves monedes a MariaDB, CSV o XML des del panell d'administració de WordPress.
• Mostra un diagnòstic independent per a cada font de dades: estat, lectura, escriptura i nombre de registres disponibles.
• Mostra les imatges de les monedes al frontend del lloc WordPress.
• Permet filtrar el catàleg per nom, país, any d'emissió i rang de valor.
• Permet ordenar el catàleg per nom, valor, any o darrera actualització, i definir un límit visible.
• Inclou un filtre específic per mostrar només les monedes que tenen imatge.
• Permet canviar la font de dades directament des del frontend quan el shortcode no fixa una font concreta.
• Mostra una vista prèvia enriquida de la font de dades activa a l'administració.

flowchart TD
    WP["WordPress"]
    Admin["Panell Admin\nResum · Diagnòstic · Configurar · Inserir · Previsualitzar"]
    SC["Shortcode\ngestio_monedes_llistat\nHero · Diagnòstic · Filtres · Resultats"]
    SM["GMWP_Source_Manager"]
    DB[("MariaDB")]
    CSV[/"CSV"/]
    XML[/"XML"/]
    WP --> Admin
    WP --> SC
    Admin --> SM
    SC --> SM
    SM --> DB
    SM --> CSV
    SM --> XML
        

4.3 Instal·lació i configuració a WordPress

# Opció A: copiar la carpeta manualment
cp -r /var/www/html/gestio_monedes/wordpress-plugin/gestio-monedes-wp /ruta/al/wordpress/wp-content/plugins/

# Opció B: pujar el ZIP des de l'administració de WordPress
/var/www/html/gestio_monedes/wordpress-plugin/gestio-monedes-wp.zip

[gestio_monedes_llistat]

# Exemple forçant MariaDB i un títol personalitzat
[gestio_monedes_llistat source="mariadb" title="Catàleg de monedes"]

4.4 Validació dels requisits de l'activitat

5. Extensió per a MediaWiki

5.1 Objectiu de l'extensió

El projecte incorpora una extensió pròpia per a MediaWiki anomenada GestioMonedes. L'objectiu és integrar el catàleg de monedes directament dins de la wiki mitjançant una pàgina especial que permet consultar, filtrar i inserir dades sense sortir de MediaWiki. La versió actual també reforça l'experiència d'ús amb una capçalera informativa, un resum ràpid de resultats, un diagnòstic visual de l'estat de cada font i controls de consulta més útils per ordenar, limitar i filtrar només les monedes que tenen imatge.

5.2 Funcionalitats implementades

La pàgina especial Especial:GestioMonedes s'ha redissenyat perquè la integració dins de la wiki no sigui només funcional, sinó també agradable i coherent amb la resta del projecte.

• Llegeix dades de monedes des de MariaDB.
• Llegeix dades des d'un arxiu CSV.
• Llegeix dades des d'un arxiu XML.
• Permet inserir noves monedes a MariaDB, CSV o XML des d'una pàgina especial de la wiki.
• Mostra un diagnòstic independent per a cada font de dades: estat, lectura, escriptura i nombre de registres disponibles.
• Mostra les imatges de les monedes amb targetes compactes, valor destacat i metadades visibles.
• Permet filtrar per nom, país, any d'emissió i valor mínim/màxim.
• Permet ordenar els resultats per nom, valor, any o darrera actualització, i definir un límit visible.
• Inclou un filtre específic per mostrar només monedes amb imatge.
• Mostra els filtres actius en forma de pastilles perquè la cerca sigui més fàcil d'interpretar.
• Inclou un panell resum amb la font activa, el total de resultats i el nombre de països representats.
• Incorpora un bloc d'ajuda contextual al formulari d'inserció per explicar validació, imatges i creació automàtica de CSV/XML.
• Disposa d'un estat buit específic quan no hi ha coincidències, evitant una sortida visual pobra o confusa.

flowchart TD
    MW["MediaWiki"]
    SP["Especial:GestioMonedes\nHero · Resum · Diagnòstic · Filtres · Inserció · Resultats"]
    SM["GestioMonedesSourceManager"]
    DB[("MariaDB")]
    CSV[/"CSV"/]
    XML[/"XML"/]
    MW --> SP
    SP --> SM
    SM <--> DB
    SM <--> CSV
    SM <--> XML
        

5.3 Instal·lació i configuració

L'extensió es carrega des de LocalSettings.php i reutilitza la configuració privada de /etc/gestio_monedes/config.local.php per obtenir la connexió MariaDB i les rutes dels fitxers CSV/XML.

wfLoadExtension( 'GestioMonedes' );
$wgGestioMonedesDefaultSource = 'mariadb';

En aquest desplegament l'extensió activa està enllaçada a la instal·lació de MediaWiki i queda disponible a: https://fmehmood.cat/mediawiki/index.php/Especial:GestioMonedes

5.4 Validació dels requisits de l'activitat

La implementació actual cobreix tant la part funcional com la presentació dins de MediaWiki. El flux de treball queda resolt des d'una única pàgina especial, sense dependències manuals ni sortides textuals poc clares.

6. Extensió per a Joomla

6.1 Objectiu de l'extensió

El projecte incorpora també una extensió pròpia per a Joomla en forma de component instal·lable: com_gestiomonedes. Aquesta implementació segueix la mateixa idea funcional que les integracions de WordPress i MediaWiki, però adaptada al model de frontend/backend propi de Joomla.

L'objectiu és disposar d'una extensió real que permeti llegir, filtrar, mostrar imatges i introduir noves dades sobre MariaDB, CSV i XML des d'un entorn Joomla completament desplegat.

A nivell visual, la vista pública actual ja no depèn del layout per defecte de Cassiopeia: utilitza una capçalera pròpia, una amplada més coherent amb la resta del projecte i una composició centrada perquè la integració no es vegi com un mòdul genèric incrustat.

6.2 Funcionalitats implementades

• Llegeix dades de monedes des de MariaDB.
• Llegeix dades des d'un arxiu CSV específic de Joomla.
• Llegeix dades des d'un arxiu XML específic de Joomla.
• Permet inserir noves monedes a MariaDB, CSV o XML des del backend del component.
• Mostra les imatges de les monedes tant al frontend com a la vista prèvia d'administració.
• Permet filtrar el catàleg per nom, país, any d'emissió i rang de valor.
• Publica una pàgina real del menú principal de Joomla per consultar el catàleg.

flowchart TD
    J["Joomla"]
    FE["Frontend\nCatàleg · Filtres · Imatges"]
    BE["Backend Admin\nConfiguració · Inserció · Vista prèvia"]
    SM["SourceManager"]
    DB[("MariaDB")]
    CSV[/"CSV"/]
    XML[/"XML"/]
    J --> FE
    J --> BE
    FE & BE --> SM
    SM <--> DB
    SM <--> CSV
    SM <--> XML
        

6.3 Instal·lació i configuració

El component es distribueix com a paquet ZIP instal·lable i es pot desplegar per línia d'ordres amb el CLI oficial de Joomla. Reutilitza la configuració privada de /etc/gestio_monedes/config.local.php i, a més, té fonts pròpies per a CSV i XML:

• /var/www/html/gestio_monedes/data/monedes_joomla.csv
• /var/www/html/gestio_monedes/data/monedes_joomla.xml

cd /var/www/html/joomla
php cli/joomla.php extension:install --path=/var/www/html/gestio_monedes/joomla-extension/com_gestiomonedes.zip

En aquest desplegament, el component ha quedat instal·lat sobre una instància Joomla real i s'ha creat també un element de menú públic a Main Menu perquè la pàgina quedi visible directament des del lloc.

6.4 Validació dels requisits de l'activitat