php-template/TODO.md

TODO - core-template

Project template for Core PHP Framework applications. This is the starter template developers clone to create new projects.

P1 - Critical / Security

Security Hardening

• Add security headers middleware - Configure X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, and CSP headers. The template should ship with secure defaults that developers can customise.

• Add CSRF protection documentation - Document that Laravel's CSRF protection is enabled by default and how to handle AJAX requests with the X-CSRF-TOKEN header (already set up in bootstrap.js via axios).

• Configure session security in .env.example - Add SESSION_SECURE_COOKIE=true (commented for production) and document that SESSION_ENCRYPT=true should be enabled for sensitive applications.

• Add rate limiting to default routes - The welcome page has no rate limiting. Consider adding basic throttle middleware to prevent abuse during development/staging.

• Document APP_KEY rotation - Add a security note about key rotation and the implications for encrypted data (sessions, cookies).

Environment Security

• Add .env.production.example - Provide a production-ready example with secure defaults (APP_DEBUG=false, SESSION_SECURE_COOKIE=true, etc.).

• Add sensitive key validation - Consider adding a boot-time check that warns if critical keys (APP_KEY, BCRYPT_ROUNDS) are using insecure defaults in production.

P2 - High Priority

Testing Infrastructure

• Add example tests - Added example tests demonstrating Pest patterns. (Fixed: 2026-01-29)

  • tests/Feature/WelcomePageTest.php - Tests welcome page (GET / returns 200)
  • tests/Feature/HealthEndpointTest.php - Tests health endpoint (GET /up returns 200)
  • tests/Unit/ExampleTest.php - Demonstrates Pest expectations syntax

• Add Pest configuration file - Created tests/Pest.php with TestCase binding, RefreshDatabase for Feature tests, and documentation for custom expectations/helpers. (Fixed: 2026-01-29)

• Configure parallel testing - Add pest.xml or configure phpunit.xml for parallel test execution.

• Add database refresh trait documentation - Document when to use RefreshDatabase vs DatabaseMigrations in tests.

Developer Experience

• Add composer scripts - Added common scripts to composer.json: lint, test, test:coverage. Also added pestphp/pest-plugin-type-coverage for coverage support. (Fixed: 2026-01-29)

• Add make:mod command documentation - The README mentions php artisan make:mod but doesn't document all available flags (--web, --api, --admin, --all).

• Create example module - Add a simple example module (e.g., app/Mod/Example/) that developers can reference or delete. This would demonstrate the module pattern better than documentation alone.

• Add VS Code workspace settings - Create .vscode/settings.json with recommended settings for PHP, Blade, and Tailwind.

• Add EditorConfig - Create .editorconfig for consistent formatting across different editors.

Configuration

• Document CDN configuration - The config/core.php references CDN settings but there's no documentation on how to configure BunnyCDN or other CDN providers.

• Add Flux Pro setup script - Consider adding a composer script or artisan command to simplify Flux Pro installation for licensed users.

• Add database configuration examples - The .env.example shows SQLite as default with commented MySQL. Add PostgreSQL example too.

P3 - Medium Priority

Code Quality

• Add strict_types to all PHP files - The AppServiceProvider.php, TestCase.php, DatabaseSeeder.php, and route files are missing declare(strict_types=1);. This contradicts the coding standards documented in CLAUDE.md.

• Add return type to artisan file - The artisan file should have proper typing for consistency.

• Standardise route file structure - The routes/api.php and routes/console.php have comments but no actual routes. Consider adding example routes or removing the unused files entirely.

• Add PHPStan/Larastan configuration - Consider adding static analysis to catch type errors and potential bugs.

Frontend

• Add Livewire to Vite config - The vite.config.js doesn't include Livewire-specific configuration for hot reloading.

• Configure Tailwind for module paths - The tailwind.config.js only scans resources/ but modules in app/Mod/*/Views/ won't be picked up. Add:

  content: [
    "./resources/**/*.blade.php",
    "./resources/**/*.js",
    "./app/Mod/**/Views/**/*.blade.php",
  ]
  

• Add Flux UI styles import - The app.css only imports Tailwind utilities. When using Flux, additional styles may be needed.

• Remove welcome.blade.php inline styles - The welcome page uses inline <style> tags instead of Tailwind classes. Consider converting to Tailwind or moving to a separate CSS file.

CI/CD

• Add missing cliff.toml - The release.yml workflow references cliff.toml for changelog generation, but this file doesn't exist in the template.

• Update actions/checkout version - The CI workflows use actions/checkout@v6 which may not exist yet. Verify and use the correct version (likely v4).

• Add Codecov configuration - Consider adding codecov.yml for customised coverage thresholds and ignore patterns.

• Add branch protection documentation - Document recommended GitHub branch protection rules for main branch.

Documentation

• Add CONTRIBUTING.md - Guide for contributors including coding standards, PR process, and testing requirements.

• Add CHANGELOG.md - Start tracking changes in a changelog file.

• Add LICENSE file - The composer.json specifies EUPL-1.2 but there's no LICENSE file in the repository.

• Improve README installation instructions - Add troubleshooting section for common issues (permission errors, missing extensions).

P4 - Low Priority

Polish

• Add favicon - The public directory has no favicon. Add a default Core PHP Framework favicon.

• Add meta tags to welcome.blade.php - Missing description, Open Graph tags, and other SEO-relevant meta tags.

• Configure error pages - Add custom 404, 500, and 503 error pages that match the Core PHP Framework branding.

• Add storage link documentation - Document when and how to run php artisan storage:link.

• Add Docker configuration - Consider adding Dockerfile and docker-compose.yml for containerised development.

Consistency

• Unify AI instruction files - There are three similar files: CLAUDE.md, GEMINI.md, and AGENTS.md. Consider consolidating into a single AI_INSTRUCTIONS.md or keeping them but ensuring they stay in sync.

• Add .gitignore entries for common IDEs - The template could benefit from more comprehensive IDE ignore patterns (JetBrains, VS Code, Sublime, etc.).

• Remove unused .idea directory files - These should be in .gitignore, not committed to the template.

P5 - Nice to Have

Features

• Add health check route customisation - The /up health endpoint is hardcoded. Consider making this configurable.

• Add deployment documentation - Include guides for deploying to common platforms (Forge, Vapor, DigitalOcean, etc.).

• Add make:mod stub customisation - Allow developers to customise the stubs used by make:mod command.

• Add queue worker configuration - Document queue setup and add example Supervisor configuration.

• Add scheduled task documentation - Document how to set up cron for Laravel's scheduler.

Tooling

• Add pre-commit hooks - Configure Husky or similar to run Pint before commits.

• Add GitHub issue templates - Create templates for bug reports and feature requests.

• Add GitHub PR template - Create a pull request template with checklist.

• Add Dependabot auto-merge - Configure auto-merge for minor/patch dependency updates.

P6 - Future / Backlog

Long-term Improvements

• Add multi-language support - Consider adding lang directory structure and documentation for i18n.

• Add API documentation generation - Integrate OpenAPI/Swagger documentation generation.

• Add performance monitoring integration - Document integration with Laravel Telescope, Debugbar, or similar.

• Add logging configuration examples - Document centralised logging setup (Papertrail, Logstash, etc.).

• Add backup configuration - Document and provide examples for database backup strategies.

---

Completed

Move items here when done, preserving them for reference.

• Add example tests (P2-049) - Added tests/Feature/WelcomePageTest.php, tests/Feature/HealthEndpointTest.php, and tests/Unit/ExampleTest.php demonstrating Pest testing patterns. (2026-01-29)
• Add Pest configuration file (P2-050) - Created tests/Pest.php with TestCase binding, RefreshDatabase for Feature tests, and placeholder documentation for custom expectations and helper functions. (2026-01-29)
• Add composer scripts (P2-051) - Added lint, test, and test:coverage scripts to composer.json. Also added pestphp/pest-plugin-type-coverage dependency. (2026-01-29)