Troubleshooting & Maintenance

Pragma CMS features a comprehensive Maintenance Dashboard (Admin > Tools > Maintenance) designed to help administrators troubleshoot issues and keep the system running at peak performance.

1. System Caches Management

Pragma CMS heavily relies on caching to achieve its fast load times. If you modify core files, update themes via FTP, or change structural routes, you might need to flush these caches manually.

• Template Cache (Twig): Clears all compiled HTML views. Essential if you have manually modified a .twig file and the changes are not reflecting on the frontend.
• Route Cache: Clears the pre-compiled PHP routing map. Use this if a newly created system page is returning a 404 error.

2. Image Transforms Regeneration

When images are uploaded, Pragma CMS generates multiple variants (thumbnail, medium, large, webp, avif). If you change your site's default image dimensions in the settings, or if an image appears broken, clicking "Clear Images" will safely delete the generated variants.

The CMS will then process the regeneration in background batches (to avoid PHP execution timeouts) using the preserved original source files (/media/source).

3. Database Health & Optimization

Over time, heavy operations (like deleting articles, creating multiple revisions, or updating settings) can fragment the database and create "Overhead" (wasted disk space).

• Overhead Detection: The dashboard scans core tables (e.g., entries, submissions) and flags any table with more than 100KB of overhead with a "Needs Opt." warning.
• Optimize Database: Triggers an OPTIMIZE TABLE MySQL command across the database to defragment rows and reclaim disk space.
• Revision Cleanup: With one click, administrators can permanently delete article/page revisions older than 30 days to significantly reduce database size.

4. Storage Cleanup (Orphaned Files Detection)

One of the most advanced troubleshooting features in Pragma CMS is the Orphan Scanner.

If a user deletes a media entry from the database, but the physical file deletion fails (due to server permission issues), the physical file remains on the disk forever, wasting storage.

The Orphan Scanner solves this by comparing the physical hard drive structure against the database schema:

1. It recursively scans the /media/source directory.
2. It cross-references every file against the original_file_path column in the media table.
3. It lists all files that exist on the disk but have no corresponding database entry.
4. Administrators can review this list and securely delete the orphaned files to reclaim server space.