Skip to content

Commit 1fd5ba4

Browse files
n0nag0nn0nag0n
committed
Added GEMINI agent instructions
1 parent 34c49c2 commit 1fd5ba4

File tree

1 file changed

+182
-0
lines changed

1 file changed

+182
-0
lines changed

‎.gemini/GEMINI.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Flight Skeleton Project Instructions
2+
3+
This document provides guidelines and best practices for structuring and developing a project using the Flight PHP framework.
4+
5+
## Instructions for AI Coding Assistants
6+
7+
As you are developing this project, follow these guidelines as close as you can. If you are unsure about something, ask for clarification before proceeding. You should feel 95% confident in the coding decisions that you make, but allow yourself an offramp if you are not sure about something to ask questions.
8+
9+
## Project Structure
10+
11+
Organize your project as follows:
12+
13+
project-root/
14+
│
15+
├── app/ # Application-specific code
16+
│ ├── commands/ # Custom CLI commands for Runway (built using adhocore/cli)
17+
│ ├── config/ # Configuration files (database, app settings, routes)
18+
│ # Key files in this folder:
19+
│ # - bootstrap.php: Bootstraps and connects the files in the config folder.
20+
│ # - routes.php: Route definitions.
21+
│ # - services.php: Service definitions (where config variables are used and injected).
22+
│ ├── controllers/ # Route controllers (e.g., HomeController.php)
23+
│ ├── logic/ # (For large projects) Business logic classes/services, called from controllers
24+
│ ├── middlewares/ # Custom middleware classes/functions
25+
│ ├── models/ # Data models (if needed, usually using flightphp/active-record)
26+
│ ├── utils/ # Utility/helper functions
27+
│ └── views/ # View templates (if using)
28+
│
29+
├── public/ # Web root (index.php, assets, etc.)
30+
│
31+
├── vendor/ # Composer dependencies
32+
│
33+
├── tests/ # Unit and integration tests
34+
│
35+
├── composer.json # Composer config
36+
│
37+
└── README.md # Project overview
38+
39+
## Development Guidelines
40+
41+
- **Controllers:** Place all route-handling logic in `app/controllers/`. Each controller should handle a specific resource or feature. For large projects, move business logic out of controllers and into the `app/logic/` directory as dedicated classes/services, and call them from your controllers. Use appropriate namespaces for organization. By default, all controllers inject the `Engine $app` variable unless this project has its own dependency injection handler.
42+
- **Namespaces:** Use lowercase namespaces for all classes in the `app/` directory. For example, `app/controllers/HomeController.php` should have the namespace `app\controllers`.
43+
- **Middlewares:** Store reusable middleware in `app/middlewares/`. Register them in your bootstrap or route files.
44+
- **Utils:** Place helper functions and utilities in `app/utils/`.
45+
- **Models:** If your app uses data models, keep them in `app/models/`.
46+
- **Views:** Store templates in `app/views/` if using a templating engine.
47+
- **Config:** Use the `app/config/` directory for configuration files. The main config file is `config.php`, which should be created by copying `config_sample.php` and updating as needed. In other main bootstrap files like bootstrap, and services.php, the $config variable is available to use to access configuration values.
48+
- **Public:** Only expose the `public/` directory to the web server. All requests should go through `public/index.php`.
49+
- **Environment:** Do not use .env files; all configuration should be managed in `app/config/config.php`.
50+
- **Routes:** Define routes in `app/config/routes.php`. Use the `$router->map()` method to register routes with all request methods or `$router->get()` for `GET $router->post()` for POST etc. and associate them with controller methods. Best practice for defining the controller is [ MyController::class, 'myMethod' ].
51+
52+
## Getting Started
53+
54+
1. Clone the repository and run `composer install`.
55+
2. Copy `app/config/config_sample.php` to `app/config/config.php` and update configuration values as needed.
56+
3. Set your web server's document root to the `public/` directory.
57+
4. Add new controllers, middlewares, and utilities as needed, following the structure above.
58+
5. Register routes and middlewares in your bootstrap file (usually `public/index.php`).
59+
60+
## CLI Commands
61+
62+
Flight projects can include custom CLI commands to automate tasks such as migrations, seeding, or maintenance. The recommended CLI tool is [flightphp/runway](https://github.com/flightphp/runway), which builds on the [adhocore/cli](https://github.com/adhocore/cli) package (not Symfony Console).
63+
64+
- Place your custom command classes in the `app/commands/` directory.
65+
- Runway will automatically discover and register commands from this directory.
66+
- All CLI commands should be built using the adhocore/cli package (do not use Symfony Console).
67+
- Use CLI commands to manage your application, generate code, or perform routine tasks.
68+
69+
Refer to the Runway documentation for details on creating and using custom commands with adhocore/cli.
70+
71+
## Additional Tips
72+
73+
- Keep controllers focused and small; delegate global or common logic to `app/utils/` when possible. For large projects, move business logic to `app/logic/` and use appropriate namespaces.
74+
- Write tests for class files in the `tests/` directory.
75+
- Use Composer for dependency management.
76+
- Document your code and update the README as your project evolves.
77+
- **Favor simplicity and minimalism:** Keep your codebase simple and avoid unnecessary abstractions or complexity. Only add dependencies when absolutely necessary, as fewer dependencies mean fewer potential issues and security risks.
78+
- **Follow coding standards:** Use PSR1 coding standards and strict comparisons (`===`). Maintain a high level of code quality and consistency throughout your project.
79+
- **Test thoroughly:** Regularly run and maintain tests for your codebase. Ensure your application works as expected.
80+
81+
For more details, see the README file or visit the Flight documentation.
82+
83+
## Suggested Packages
84+
85+
Flight is highly extensible. Here are some recommended packages and plugins for common needs:
86+
87+
- **ORM / Database:**
88+
- [flightphp/core](https://github.com/flightphp/core) PdoWrapper (simple PDO wrapper)
89+
- [flightphp/active-record](https://github.com/flightphp/active-record) (official ORM/Mapper)
90+
- [byjg/php-migration](https://github.com/byjg/php-migration) (database migrations)
91+
- **Session:**
92+
- [flightphp/session](https://github.com/flightphp/session) (official session library)
93+
- [Ghostff/Session](https://github.com/Ghostff/Session) (advanced session manager)
94+
- **Permissions:**
95+
- [flightphp/permissions](https://github.com/flightphp/permissions) (official permissions library)
96+
- **Caching:**
97+
- [flightphp/cache](https://github.com/flightphp/cache) (official in-file caching)
98+
- **CLI:**
99+
- [flightphp/runway](https://github.com/flightphp/runway) (official CLI tool, built on adhocore/cli)
100+
- **Cookies:**
101+
- [overclokk/cookie](https://github.com/overclokk/cookie) (cookie management)
102+
- **Debugging:**
103+
- [tracy/tracy](https://github.com/nette/tracy) (error handler and debugger)
104+
- [flightphp/tracy-extensions](https://github.com/flightphp/tracy-extensions) (Flight-specific Tracy panels)
105+
- **APM (Performance Monitoring):**
106+
- [flightphp/apm](https://github.com/flightphp/apm) (application performance monitoring)
107+
- **Encryption:**
108+
- [defuse/php-encryption](https://github.com/defuse/php-encryption) (encryption/decryption)
109+
- **Job Queue:**
110+
- [n0nag0n/simple-job-queue](https://github.com/n0nag0n/simple-job-queue) (asynchronous job processing)
111+
- **Templating:**
112+
- [latte/latte](https://github.com/nette/latte) (recommended templating engine)
113+
- (Deprecated) flightphp/core View (basic, not recommended for large projects)
114+
- **API Documentation:**betaflightphp
115+
- [SwaggerUI](https://github.com/zircote/swagger-php) (Swagger/OpenAPI documentation)
116+
- [Flight OpenAPI Generator](https://daniel-schreiber.de/blog/flightphp-openapi-generator.html) (API-first approach)
117+
118+
Choose the packages that best fit your project's needs. Official Flight packages are recommended for core functionality.
119+
120+
## Security Best Practices (Condensed)
121+
122+
All code must follow secure coding practices. Always treat user input as untrusted. Key requirements:
123+
124+
### Cross Site Scripting (XSS)
125+
- Always escape user output in views.
126+
- Use Flight’s view class or a templating engine (e.g., Latte) for auto-escaping.
127+
```php
128+
Flight::view()->set('name', $name);
129+
Flight::view()->render('template', ['name' => $name]);
130+
```
131+
132+
### SQL Injection
133+
- Never concatenate user input in SQL.
134+
- Always use prepared statements or parameterized queries.
135+
- Preferred usage for raw SQL is with flight\database\PdoWrapper
136+
```php
137+
$statement = Flight::db()->fetchRow('SELECT * FROM users WHERE username = :username', [':username' => $username]);
138+
```
139+
140+
### CORS
141+
- Set CORS headers via utility or middleware before `Flight::start()`.
142+
- Only allow trusted origins.
143+
```php
144+
Flight::before('start', [ (new CorsUtil()), 'set' ]);
145+
```
146+
147+
### Error Handling
148+
- Don’t display sensitive errors in production; log them instead.
149+
- Use `Flight::halt()` for controlled responses.
150+
```php
151+
if (ENVIRONMENT === 'production') {
152+
ini_set('display_errors', 0);
153+
ini_set('log_errors', 1);
154+
}
155+
Flight::halt(403, 'Access denied');
156+
```
157+
158+
### Input Sanitization
159+
- Sanitize and validate all user input.
160+
```php
161+
$clean_input = filter_var(Flight::request()->data->input, FILTER_SANITIZE_STRING);
162+
```
163+
164+
### Password Hashing
165+
- Always hash passwords; never store plain text.
166+
```php
167+
$hashed_password = password_hash($password, PASSWORD_DEFAULT);
168+
if (password_verify($password, $stored_hash)) { /* Password matches */ }
169+
```
170+
171+
### Rate Limiting
172+
- Use caching or middleware to limit repeated requests.
173+
```php
174+
Flight::before('start', function() {
175+
$cache = Flight::cache();
176+
$ip = Flight::request()->ip;
177+
$key = "rate_limit_{$ip}";
178+
$attempts = (int) $cache->get($key);
179+
if ($attempts >= 10) Flight::halt(429, 'Too many requests');
180+
$cache->set($key, $attempts + 1, 60);
181+
});
182+
```

0 commit comments

Comments
 (0)