1. INTRODUCTION

Welcome to the Kristal Framework! The main configuration files are located in the project root and its config/ folder. Here’s a quick breakdown:

• .htaccess: Handles page URLs, HTTPS redirects and file access.
• config/config-example.php: Provides the settings to copy when starting a project.
• config/config.php: Holds database and email details, session settings, maintenance mode, production mode and JS/SCSS compilation options.

Copy config/config-example.php to config/config.php, then edit the settings in your new file. Start by choosing session and cookie names for your website:

define("SESSION_NAME", "MyWebsiteSession");
define("COOKIE_NAME", "MyWebsiteCookie");

Server Requirements

• PHP 8.3 or later within PHP 8.x.
• Apache or LiteSpeed with .htaccess support.
• Composer.
• Permission to write session data and generated files.

Database Requirements

• PHP’s PDO and PDO MySQL extensions.
• A MySQL database, created before connecting.

For image conversion, enable GD with WebP support and EXIF. Sitemap generation also needs SimpleXML and DOM.

2. COMPOSER

The Kristal Framework leverages Composer for its backend setup and dependency management. You can find composer.json in the project root. Edit it when adding third-party libraries.

Initializing the Backend

If the vendor/ folder is missing, run this command from the project root:

composer install --prefer-dist --optimize-autoloader

Composer installs the package versions listed in composer.lock and creates vendor/autoload.php.

Updating Packages

Use this command when you’re ready to update packages:

composer update --prefer-dist --optimize-autoloader

Test the website after updating. Packages with an exact version in composer.json keep that version until you change it.

Troubleshooting

If PHP cannot find a class, check its name, namespace and filename, then rebuild the autoloader:

composer dump-autoload --optimize

If autoload.php itself is missing, run the installation command first.

3. HTACCESS

The supplied .htaccess file sends page requests to index.php, allowing URLs such as /about/. It also redirects visitors to HTTPS.

#RewriteCond %{HTTPS} !=on
#RewriteCond %{HTTP:X-Forwarded-Proto} !^https$ [NC]
#RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=308,L]

If your hosting uses a reverse proxy, make sure PHP recognizes HTTPS too. index.php checks $_SERVER[”HTTPS”].

Troubleshooting

If page URLs don’t work, check that your server reads .htaccess and supports URL rewriting. The current routing rules use an internal path to index.php:

RewriteEngine On
RewriteBase /

RewriteRule ^index.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule . index.php [L,QSA]

Keep the surrounding rules when editing the file. This setup expects the website at the domain root; subfolder hosting requires changes to both the rewrite rules and the framework paths.

4. CONCLUSION

You can now open your website and start creating pages. Follow Routes to connect a URL to a method, then Pages to add its content.

While building, keep PRODUCTION_MODE set to false. Before publishing, generate the CSS, JavaScript and WebP files your pages need, then use:

define("PRODUCTION_MODE", true);
define("ENABLE_DEBUG_DISPLAY", false);
define("ENABLE_DEBUG_LOG", true);

Upload the generated files too. Production mode skips automatic CSS/JS compilation and WebP generation. Choose a writable DEBUG_LOG_PATH so errors can still be logged.