Troubleshooting

Common Issues

mod_rewrite Not Working

This is the most common issue. MINI requires mod_rewrite for clean URLs.

Symptoms:

404 errors on all pages except homepage
“Not Found” errors when accessing routes
URLs like /songs don’t work

Solutions:

1. Enable mod_rewrite module

Ubuntu/Debian
CentOS/RHEL
XAMPP

sudo a2enmod rewrite
sudo service apache2 restart

Verify it’s enabled:

apache2ctl -M | grep rewrite
# Should show: rewrite_module (shared)

Edit /etc/httpd/conf/httpd.conf and ensure:

LoadModule rewrite_module modules/mod_rewrite.so

Restart:

sudo systemctl restart httpd

Open xampp/apache/conf/httpd.conf and uncomment:

LoadModule rewrite_module modules/mod_rewrite.so

Restart Apache via XAMPP control panel.

2. Enable .htaccess support

Your virtual host must allow .htaccess overrides:

<Directory "/var/www/html/myproject/public">
    AllowOverride All  # This line is crucial
    Require all granted
</Directory>

If AllowOverride is set to None, .htaccess files are ignored!

3. Verify .htaccess exists

Check that /public/.htaccess exists and is readable:

ls -la /var/www/html/myproject/public/.htaccess

# Should show: -rw-r--r-- ... .htaccess

If missing, create it with the correct content from server setup.

4. Check file permissions

The .htaccess file must be readable by the web server:

chmod 644 /var/www/html/myproject/public/.htaccess

Alternative solution: If you cannot enable mod_rewrite, use TINY, MINI’s smaller brother that works without mod_rewrite.

Database Connection Errors

Symptoms:

“Could not connect to database” errors
PDO exceptions
Blank pages when accessing database-dependent routes

Solutions:

Verify database credentials

Edit application/config/config.php5-59:

define('DB_TYPE', 'mysql');
define('DB_HOST', '127.0.0.1');
define('DB_NAME', 'mini');
define('DB_USER', 'root');
define('DB_PASS', 'your_password');  // Change this!
define('DB_CHARSET', 'utf8');

Test database connection

mysql -h 127.0.0.1 -u root -p mini
# Enter password when prompted

If this fails, your credentials are incorrect.

Check database exists

mysql -u root -p -e "SHOW DATABASES LIKE 'mini';"

If empty, create it:

mysql -u root -p < _install/01-create-database.sql
mysql -u root -p < _install/02-create-table-song.sql
mysql -u root -p < _install/03-insert-demo-data-into-table-song.sql

Verify PDO MySQL extension

php -m | grep pdo_mysql

If not found, install it:

# Ubuntu/Debian
sudo apt-get install php-mysql

# CentOS/RHEL
sudo yum install php-mysql

MySQL socket connection error

If you see “Can’t connect to local MySQL server through socket”:Change DB_HOST from localhost to 127.0.0.1:

define('DB_HOST', '127.0.0.1');  // Use IP instead of localhost

This forces PDO to use TCP instead of socket connection.

404 Errors on All Routes

Symptoms:

Homepage works, but all other routes return 404
Apache error: “File not found”

Diagnosis:

Check document root

Your document root MUST point to /public:

DocumentRoot "/var/www/html/myproject/public"  # Correct
# NOT
DocumentRoot "/var/www/html/myproject"  # Wrong!

Test .htaccess is working

Add this to the top of /public/.htaccess:

# TEST
Redirect 301 /test http://google.com

Visit http://yoursite.com/test. If you’re NOT redirected to Google, .htaccess is not being processed.Remove the test line after checking.

Check Apache error log

# Ubuntu/Debian
sudo tail -f /var/log/apache2/error.log

# CentOS/RHEL
sudo tail -f /var/log/httpd/error_log

# XAMPP
# Check xampp/apache/logs/error.log

Look for .htaccess or rewrite-related errors.

Permission Denied Errors

Symptoms:

“Permission denied” in error logs
403 Forbidden errors
Cannot read/write files

Solutions:

cd /var/www/html/myproject

# Fix ownership
sudo chown -R www-data:www-data .

# Fix directory permissions
sudo find . -type d -exec chmod 755 {} \;

# Fix file permissions
sudo find . -type f -exec chmod 644 {} \;

# Secure config file
sudo chmod 600 application/config/config.php

Replace www-data with your web server user:

Ubuntu/Debian: www-data
CentOS/RHEL: apache
Mac: _www

PHP Version Compatibility

PHP 7.0+ Error Class Issue

PHP 7.0 introduced an internal Error class, conflicting with MINI’s original Error class.

Solution: MINI has been updated to use Problem instead of Error. If you see errors about the Error class:

Update to the latest MINI version (already renamed to Problem)
Or manually rename:
- application/controller/error.php → problem.php
- Inside the file, change class Error → class Problem
- Update references in application/core/application.php

From README:

The project was written in PHP5 times, but with the release of PHP7 it’s not possible anymore to name a class “Error” as PHP itself has a internal Error class now. Renaming was the most simple solution.

PHP 8.0+ Compatibility

MINI is not extensively tested with PHP 8.0+ but should work fine. Report issues on GitHub.

Common PHP 8 issues:

Deprecation notices for certain syntax
Type juggling changes
Named parameters

Enable error reporting to diagnose:

application/config/config.php

define('ENVIRONMENT', 'development');

if (ENVIRONMENT == 'development') {
    error_reporting(E_ALL);
    ini_set("display_errors", 1);
}

nginx Issues

PHP files downloading instead of executing

Cause: PHP-FPM not configured correctly. Solution:

Verify PHP-FPM is running:

sudo service php7.4-fpm status  # Adjust version

Check socket path in nginx config:

location ~ \.(php)$ {
    # Use correct socket path for your PHP version
    fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Test nginx config:

sudo nginx -t
sudo service nginx reload

404 errors with nginx

Check the try_files directive:

location / {
    index index.php;
    try_files /$uri /$uri/ /index.php?url=$uri;
}

See GitHub issue #55 for detailed nginx discussion.

Subdirectory Installation Issues

Symptoms:

Application works on root domain but not in subdirectory
CSS/JS not loading in subdirectory
Routes broken in subdirectory

Solutions:

1. Verify auto-detection is working

MINI auto-detects subdirectories. Check application/config/config.php8:

define('URL_SUB_FOLDER', str_replace(URL_PUBLIC_FOLDER, '', dirname($_SERVER['SCRIPT_NAME'])));
define('URL', URL_PROTOCOL . URL_DOMAIN . URL_SUB_FOLDER);

Debug by adding temporarily:

echo URL; // Should show http://yoursite.com/subfolder/
exit;

2. Ensure .htaccess is present

The /public/.htaccess must be present in the subdirectory:

/var/www/html/subfolder/myproject/public/.htaccess

3. Check base href in templates

If CSS/JS not loading, verify paths in application/view/_templates/header.php use the URL constant:

<link href="<?php echo URL; ?>css/style.css" rel="stylesheet">

Blank White Pages

Symptoms:

Completely blank page
No error messages
Nothing in browser console

Diagnosis:

Enable error reporting

Edit application/config/config.php3:

define('ENVIRONMENT', 'development');

Check PHP error log

# Ubuntu/Debian
sudo tail -f /var/log/apache2/error.log

# Or check PHP error log location:
php -i | grep error_log

Check PHP syntax

php -l application/core/application.php
php -l application/controller/home.php
# etc.

Increase PHP memory

Add to .htaccess or php.ini:

memory_limit = 128M

Debugging Tips

Enable Development Mode

application/config/config.php

define('ENVIRONMENT', 'development');

if (ENVIRONMENT == 'development') {
    error_reporting(E_ALL);
    ini_set("display_errors", 1);
}

Always set to 'production' on live sites!

Debug PDO Queries

MINI includes a PDO debugger tool:

$sql = "SELECT id, artist, track FROM song WHERE id = :song_id";
$query = $this->db->prepare($sql);
$parameters = array(':song_id' => $song_id);

// Debug: Show the query with parameters
echo Helper::debugPDO($sql, $parameters);

$query->execute($parameters);

Find the debugger in application/libs/helper.php.

Check Apache/nginx Logs

# Apache (Ubuntu/Debian)
sudo tail -f /var/log/apache2/error.log
sudo tail -f /var/log/apache2/access.log

# Apache (CentOS/RHEL)
sudo tail -f /var/log/httpd/error_log
sudo tail -f /var/log/httpd/access_log

# nginx
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

# XAMPP
# Check xampp/apache/logs/error.log

Test PHP Configuration

Create info.php in /public:

<?php
phpinfo();

Access http://yoursite.com/info.php and check:

PHP version
Loaded extensions (PDO, pdo_mysql)
Configuration directives

Delete info.php after testing! It exposes sensitive information.

Test URL Rewriting

Create test.php in /public:

<?php
echo "Direct file access works!";
echo "<br>URL: " . $_SERVER['REQUEST_URI'];
echo "<br>SCRIPT_NAME: " . $_SERVER['SCRIPT_NAME'];

Test:

Direct access: http://yoursite.com/test.php → Should work
Routed access: http://yoursite.com/home → Should show MINI page

If direct works but routing doesn’t, it’s a mod_rewrite issue.

Performance Issues

Slow Page Load

Enable OPcache

For PHP 5.5+:

php.ini

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=4000
opcache.revalidate_freq=60

Restart Apache/PHP-FPM after changes.

Optimize database queries

Use the PDO debugger to identify slow queries:

echo Helper::debugPDO($sql, $parameters);

Add indexes to frequently queried columns.

Check database connection

Ensure DB_HOST uses the fastest connection method:

Socket: localhost (fastest, if available)
TCP: 127.0.0.1 (if socket fails)

Getting Help

GitHub Issues

Report bugs and request features

Stack Overflow

Ask questions and search existing answers

Documentation

Browse the complete documentation

Source Code

View the source code on GitHub

When reporting issues, include:

PHP version (php -v)
Web server (Apache/nginx) version
Operating system
Error messages from logs
Steps to reproduce

Quick Reference Checklist

PHP requirements

✅ PHP 5.3.0+ installed
✅ PDO and pdo_mysql extensions enabled
✅ Error reporting configured

Web server

✅ mod_rewrite enabled (Apache)
✅ Virtual host points to /public
✅ AllowOverride All set
✅ .htaccess present and readable

Database

✅ MySQL installed and running
✅ Database created
✅ Tables imported
✅ Credentials in config.php correct

Permissions

✅ Files owned by web server user
✅ Directories: 755
✅ Files: 644
✅ Config: 600

Security

✅ Document root = /public only
✅ Directory listing disabled
✅ .git not accessible
✅ Error reporting off in production

Next Steps

Back to Server Setup

Review server configuration steps

Get Started

Core Concepts

Guides

Deployment

Troubleshooting

Common Issues

mod_rewrite Not Working

Database Connection Errors

404 Errors on All Routes

Permission Denied Errors

PHP Version Compatibility

PHP 7.0+ Error Class Issue

PHP 8.0+ Compatibility

nginx Issues

PHP files downloading instead of executing

404 errors with nginx

Subdirectory Installation Issues

Blank White Pages

Debugging Tips

Enable Development Mode

Debug PDO Queries

Check Apache/nginx Logs

Test PHP Configuration

Test URL Rewriting

Performance Issues

Slow Page Load

Getting Help

GitHub Issues

Stack Overflow

Documentation

Source Code

Quick Reference Checklist

Next Steps

Back to Server Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

​Common Issues

​mod_rewrite Not Working

​Database Connection Errors

​404 Errors on All Routes

​Permission Denied Errors

​PHP Version Compatibility

​PHP 7.0+ Error Class Issue

​PHP 8.0+ Compatibility

​nginx Issues

​PHP files downloading instead of executing

​404 errors with nginx

​Subdirectory Installation Issues

​Blank White Pages

​Debugging Tips

​Enable Development Mode

​Debug PDO Queries

​Check Apache/nginx Logs

​Test PHP Configuration

​Test URL Rewriting

​Performance Issues

​Slow Page Load

​Getting Help

GitHub Issues

Stack Overflow

Documentation

Source Code

​Quick Reference Checklist

​Next Steps

Back to Server Setup

Build docs developers (and LLMs) love

Common Issues

mod_rewrite Not Working

Database Connection Errors

404 Errors on All Routes

Permission Denied Errors

PHP Version Compatibility

PHP 7.0+ Error Class Issue

PHP 8.0+ Compatibility

nginx Issues

PHP files downloading instead of executing

404 errors with nginx

Subdirectory Installation Issues

Blank White Pages

Debugging Tips

Enable Development Mode

Debug PDO Queries

Check Apache/nginx Logs

Test PHP Configuration

Test URL Rewriting

Performance Issues

Slow Page Load

Getting Help

Quick Reference Checklist

Next Steps