codewithphp copilot-instructions.md

Copilot AI Agent Instructions for PHP-From-Scratch

Project Overview

• Purpose: This repo is a comprehensive, example-driven PHP learning series. It uses VitePress for documentation and organizes code samples by chapter.
• Structure:
  • docs/ — VitePress content root (site config, landing, series, chapters, code)
  • docs/series/<series>/chapters/ — Numbered markdown chapters
  • docs/series/<series>/code/ — Code samples for each chapter, colocated
  • .github/workflows/ — GitHub Actions for VitePress deploy
  • .cursor/rules/ — Project structure and navigation rules
  • package.json — VitePress scripts (dev/build/preview)

Key Conventions & Patterns

• Each series is self-contained: All content, code, and navigation for a series lives under its own folder in docs/series/.
• Code samples: Each chapter has matching code in code/, named by chapter and topic. Exercise solutions are in solutions/ subfolders.
• Markdown-first: All learning content is authored in markdown, with code blocks and explanations inline.
• PSR-12/PSR-4: Code samples follow modern PHP standards (see Chapter 16 for details).
• No framework dependencies unless in framework-specific chapters (e.g., Laravel, Symfony).
• Composer: Used only in relevant chapters; not required for the whole repo.

Developer Workflows

• Preview docs locally:

  npm install
  npm run docs:dev
  # Visit http://localhost:5173
  

• Build for production:

  npm run docs:build
  

• Deploy:
  • GitHub Actions auto-deploys main branch to Pages using .github/workflows/deploy.yml.
• Test code samples:
  • Run PHP scripts directly: php <filename>.php
  • Some chapters include test scripts or expected output in comments/README.
• Debugging:
  • Use VS Code with Xdebug (see 00-setup/README.md for setup and troubleshooting).

Integration Points

• VitePress: All site config in docs/.vitepress/config.ts.
• GitHub Pages: Deploy via Actions; see .github/workflows/.
• Composer: Only in chapters that teach dependency management (not global).