adjustments to reorder and recomment some core configs

n0nag0n · n0nag0n · commit 0d3c369ed11e · 2025-09-05T18:58:13.000-06:00
diff --git a/app/config/bootstrap.php b/app/config/bootstrap.php
@@ -23,25 +23,6 @@
  */
 $config = require('config.php');
 
-// Whip out the ol' router and we'll pass that to the routes file
-$router = $app->router();
-
-/*
- * Load the routes file. the $router variable above is passed into the routes.php
- * file below so that you can define routes in that file.
- * A route is really just a URL, but saying route makes you sound cooler.
- * When someone hits that URL, you point them to a function or method 
- * that will handle the request.
- */
-require('routes.php');
-/*
- * You additionally could just define the routes in this file. It's up to you.
- * Example:
-	$router->get('/', function() {
-		echo 'Hello World!';
-	});
-*/
-
 /*
  * Load the services file.
  * A "service" is basically something special that you want to use in your app.
@@ -59,6 +40,18 @@
  */ 
 require('services.php');
 
+// Whip out the ol' router and we'll pass that to the routes file
+$router = $app->router();
+
+/*
+ * Load the routes file. the $router variable above is passed into the routes.php
+ * file below so that you can define routes in that file.
+ * A route is really just a URL, but saying route makes you sound cooler.
+ * When someone hits that URL, you point them to a function or method 
+ * that will handle the request.
+ */
+require('routes.php');
+
 // At this point, your app should have all the instructions it needs and it'll
 // "start" processing everything. This is where the magic happens.
 $app->start();
diff --git a/app/config/config_sample.php b/app/config/config_sample.php
@@ -1,86 +1,83 @@
 <?php
 
-use flight\debug\tracy\TracyExtensionLoader;
-use Tracy\Debugger;
+/**********************************************
+ *      FlightPHP Skeleton Sample Config      *
+ **********************************************
+ *
+ * Copy this file to config.php and update values as needed.
+ * All settings are required unless marked as optional.
+ *
+ * Example:
+ *   cp app/config/config_sample.php app/config/config.php
+ *
+ * This file is NOT tracked by git. Store sensitive credentials here.
+ **********************************************/
 
-// Set the default timezone
-date_default_timezone_set('America/New_York');
+/**********************************************
+ *         Application Environment            *
+ **********************************************/
+// Set your timezone (e.g., 'America/New_York', 'UTC')
+date_default_timezone_set('UTC');
 
-// Set the error reporting level
+// Error reporting level (E_ALL recommended for development)
 error_reporting(E_ALL);
 
-// Set the default character encoding
-if(function_exists('mb_internal_encoding') === true) {
+// Character encoding
+if (function_exists('mb_internal_encoding') === true) {
 	mb_internal_encoding('UTF-8');
 }
 
-// Set the default locale
-if(function_exists('setlocale') === true) {
+// Default Locale Change as needed or feel free to remove.
+if (function_exists('setlocale') === true) {
 	setlocale(LC_ALL, 'en_US.UTF-8');
 }
 
+/**********************************************
+ *           FlightPHP Core Settings          *
+ **********************************************/
+
 // Get the $app var to use below
-if(empty($app)) {
+if (empty($app) === true) {
 	$app = Flight::app();
 }
 
-// if you want to load classes that have underscores in them, comment out the following line
-// Loader::setV2ClassLoading(false);
-
 // This autoloads your code in the app directory so you don't have to require_once everything
+// You'll need to namespace your classes with "app\folder\" to include them properly
 $app->path(__DIR__ . $ds . '..' . $ds . '..');
 
-// This is where you can set some flight config variables. 
-$app->set('flight.base_url', '/'); // if this is in a subdirectory, you'll need to change this
-$app->set('flight.case_sensitive', false); // if you want case sensitive routes, set this to true
-$app->set('flight.log_errors', true); // if you want to log errors, set this to true
-$app->set('flight.handle_errors', false); // if you want flight to handle errors, set this to true, otherwise Tracy will handle them
-$app->set('flight.views.path', __DIR__ . $ds . '..' . $ds . 'views'); // set the path to your view/template/ui files
-$app->set('flight.views.extension', '.php'); // set the file extension for your view/template/ui files
-$app->set('flight.content_length', false); // if flight should send a content length header
+// Core config variables
+$app->set('flight.base_url', '/',);           // Base URL for your app. Change if app is in a subdirectory (e.g., '/myapp/')
+$app->set('flight.case_sensitive', false);    // Set true for case sensitive routes. Default: false
+$app->set('flight.log_errors', true);         // Log errors to file. Recommended: true in production
+$app->set('flight.handle_errors', false);     // Let Tracy handle errors if false. Set true to use Flight's error handler
+$app->set('flight.views.path', __DIR__ . $ds . '..' . $ds . 'views'); // Path to views/templates
+$app->set('flight.views.extension', '.php');  // View file extension (e.g., '.php', '.latte')
+$app->set('flight.content_length', false);    // Send content length header. Usually false unless required by proxy
 
-/* 
- * Get Tracy up and running
- * 
- * There lots of setup options for Tracy! Logs, emails, clicking to
- * open in your editor and a lot more!
- * Check out the docs here:
- * https://tracy.nette.org/
- */
-Debugger::enable(); // auto tries to figure out your environment
-// Debugger::enable(Debugger::DEVELOPMENT) // sometimes you have to be explicit (also Debugger::PRODUCTION)
-// Debugger::enable('23.75.345.200'); // you can also provide an array of IP addresses
-Debugger::$logDirectory = __DIR__ . $ds . '..' . $ds . 'log';
-Debugger::$strictMode = true; // display all errors
-// Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices
-if (Debugger::$showBar && php_sapi_name() !== 'cli') {
-	(new TracyExtensionLoader($app));
-}
-
-/* 
- * This is where you will store database credentials, api credentials
- * and other sensitive information. This file will not be tracked by git
- * as you shouldn't be pushing sensitive information to a public or private
- * repository.
- * 
- * What you store here is totally up to you.
- */
+/**********************************************
+ *           User Configuration               *
+ **********************************************/
 return [
+	/**************************************
+	 *         Database Settings          *
+	 **************************************/
 	'database' => [
-		// uncomment the below 4 lines for mysql
-		// 'host' => 'localhost',
-		// 'dbname' => 'dbname',
-		// 'user' => 'user',
-		// 'password' => 'password'
+		// MySQL Example:
+		// 'host'     => 'localhost',      // Database host (e.g., 'localhost', 'db.example.com')
+		// 'dbname'   => 'your_db_name',   // Database name (e.g., 'flightphp')
+		// 'user'     => 'your_username',  // Database user (e.g., 'root')
+		// 'password' => 'your_password',  // Database password (never commit real passwords)
 
-		// uncomment the following line for sqlite
-		// 'file_path' => __DIR__ . $ds . '..' . $ds . 'database.sqlite'
+		// SQLite Example:
+		// 'file_path' => __DIR__ . $ds . '..' . $ds . 'database.sqlite', // Path to SQLite file
 	],
 
-	// this is just here for an example
+	// Google OAuth Credentials
 	// 'google_oauth' => [
-	// 	'client_id' => 'client_id',
-	// 	'client_secret' => 'client_secret',
-	// 	'redirect_uri' => 'redirect_uri'
+	//     'client_id'     => 'your_client_id',     // Google API client ID
+	//     'client_secret' => 'your_client_secret', // Google API client secret
+	//     'redirect_uri'  => 'your_redirect_uri',  // Redirect URI for OAuth callback
 	// ],
+
+	// Add more configuration sections below as needed
 ];
diff --git a/app/config/routes.php b/app/config/routes.php
@@ -16,9 +16,8 @@
 	echo '<h1>Hello world! Oh hey '.$name.'!</h1>';
 });
 
-$router->group('/api', function() use ($router, $app) {
-	$Api_Example_Controller = new ApiExampleController($app);
-	$router->get('/users', [ $Api_Example_Controller, 'getUsers' ]);
-	$router->get('/users/@id:[0-9]', [ $Api_Example_Controller, 'getUser' ]);
-	$router->post('/users/@id:[0-9]', [ $Api_Example_Controller, 'updateUser' ]);
+$router->group('/api', function() use ($router) {
+	$router->get('/users', [ ApiExampleController::class, 'getUsers' ]);
+	$router->get('/users/@id:[0-9]', [ ApiExampleController::class, 'getUser' ]);
+	$router->post('/users/@id:[0-9]', [ ApiExampleController::class, 'updateUser' ]);
 });
diff --git a/app/config/services.php b/app/config/services.php
@@ -3,26 +3,100 @@
 use flight\Engine;
 use flight\database\PdoWrapper;
 use flight\debug\database\PdoQueryCapture;
+use flight\debug\tracy\TracyExtensionLoader;
 use Tracy\Debugger;
 
-/** 
- * @var array $config This comes from the returned array at the bottom of the config.php file
- * @var Engine $app
- */
+/*********************************************
+ *         FlightPHP Service Setup           *
+ *********************************************
+ * This file registers services and integrations
+ * for your FlightPHP application. Edit as needed.
+ *
+ * @var array  $config  From config.php
+ * @var Engine $app     FlightPHP app instance
+ **********************************************/
 
-// Uncomment the following line for MySQL
+
+
+/*********************************************
+ *           Session Service Setup           *
+ *********************************************
+ * To enable sessions in FlightPHP, register the session service.
+ * Docs: https://docs.flightphp.com/en/v3/awesome-plugins/session
+ *
+ * Example:
+ *   $app->register('session', \flight\session\Session::class, [
+ *       [
+ *           'cookie_name' => 'flight_session', // Name of the session cookie
+ *           'timeout'     => 3600,             // Session timeout in seconds
+ *           // ...other options...
+ *       ]
+ *   ]);
+ *
+ * For advanced options, see the plugin documentation above.
+ **********************************************/
+
+/*********************************************
+ *           Tracy Debugger Setup            *
+ *********************************************
+ * Tracy is a powerful error handler and debugger for PHP.
+ * Docs: https://tracy.nette.org/
+ *
+ * Key Tracy configuration options:
+ *   - Debugger::enable([mode], [ip]);
+ *       - mode: Debugger::Development or Debugger::Production
+ *       - ip: restrict debug bar to specific IP(s)
+ *   - Debugger::$logDirectory: where error logs are stored
+ *   - Debugger::$strictMode: show all errors (true/E_ALL), or filter out deprecated notices
+ *   - Debugger::$showBar: show/hide debug bar (auto-detected, can be forced)
+ *   - Debugger::$maxLen: max length of dumped variables
+ *   - Debugger::$maxDepth: max depth of dumped structures
+ *   - Debugger::$editor: configure clickable file links (see docs)
+ *   - Debugger::$email: send error notifications to email
+ *
+ * Example Tracy setups:
+ *   Debugger::enable(); // Auto-detects environment
+ *   Debugger::enable(Debugger::Development); // Explicitly set environment
+ *   Debugger::enable('23.75.345.200'); // Restrict debug bar to specific IPs
+ *
+ * For more options, see https://tracy.nette.org/en/configuration
+ **********************************************/
+Debugger::enable(); // Auto-detects environment
+// Debugger::enable(Debugger::Development); // Explicitly set environment
+// Debugger::enable('23.75.345.200'); // Restrict debug bar to specific IPs
+Debugger::$logDirectory = __DIR__ . $ds . '..' . $ds . 'log'; // Log directory
+Debugger::$strictMode = true; // Show all errors (set to E_ALL & ~E_DEPRECATED for less noise)
+// Debugger::$maxLen = 1000; // Max length of dumped variables (default: 150)
+// Debugger::$maxDepth = 5; // Max depth of dumped structures (default: 3)
+// Debugger::$editor = 'vscode'; // Enable clickable file links in debug bar
+// Debugger::$email = 'your@email.com'; // Send error notifications
+if (Debugger::$showBar === true && php_sapi_name() !== 'cli') {
+	(new TracyExtensionLoader($app)); // Load FlightPHP Tracy extensions
+}
+
+/**********************************************
+ *           Database Service Setup           *
+ **********************************************/
+// Uncomment and configure the following for your database:
+
+// MySQL Example:
 // $dsn = 'mysql:host=' . $config['database']['host'] . ';dbname=' . $config['database']['dbname'] . ';charset=utf8mb4';
 
-// Uncomment the following line for SQLite
+// SQLite Example:
 // $dsn = 'sqlite:' . $config['database']['file_path'];
 
-// Uncomment the below lines if you want to add a Flight::db() service
-// In development, you'll want the class that captures the queries for you. In production, not so much.
+// Register Flight::db() service
+// In development, use PdoQueryCapture to log queries; in production, use PdoWrapper for performance.
 // $pdoClass = Debugger::$showBar === true ? PdoQueryCapture::class : PdoWrapper::class;
 // $app->register('db', $pdoClass, [ $dsn, $config['database']['user'] ?? null, $config['database']['password'] ?? null ]);
 
-// Got google oauth stuff? You could register that here
+/**********************************************
+ *         Third-Party Integrations           *
+ **********************************************/
+// Google OAuth Example:
 // $app->register('google_oauth', Google_Client::class, [ $config['google_oauth'] ]);
 
-// Redis? This is where you'd set that up
+// Redis Example:
 // $app->register('redis', Redis::class, [ $config['redis']['host'], $config['redis']['port'] ]);
+
+// Add more service registrations below as needed
