# Osumi Framework - LLM Guide (llms.txt)

Osumi Framework is a PHP framework to build web apps and APIs with:
- Routing (ORoute)
- Components (OComponent)
- ORM models (OModel) using PHP Attributes (#[OField], #[OPK], etc.)
- CLI tasks (OTask)

This document is optimized for LLMs (ChatGPT, Copilot, Gemini).
Prefer code examples and short, actionable answers.

## Version
- Framework: 9.8
- PHP: 8.3+ (works on 8.5)

## Installation
- Requires Composer
- Typical entrypoint: public/index.php
- Autoload: PSR-4

Example:
1) composer create-project osumionline/new
2) php -S localhost:8000 -t public
3) open http://localhost:8000

## Project structure (typical)
- public/index.php (entrypoint)
- src/ (application code)
- src/Config/ (config)
- src/Component/ (components + templates)
- src/Module/ (modules/components used as actions)
- src/Model/ (ORM models)
- src/Routes/ (routes)
- src/Service/ (services)
- src/Task/ (CLI tasks)

## Core concepts
1) Routing
- Define routes (GET/POST/PUT/DELETE) and map to components/actions.
- Grouping/prefixing routes supported.
- Lifecycle of a route is:
  - User requests a URL
  - If route is not defined 404 page is shown (unless something else is defined on Config.json)
  - If route is matched, the defined component is called
  - If the component has a run() function, if it has a DTO defined as parameter the data will be parsed to it and given to it. Otherwise a generic ORequest object will be passed with data parameters from the URL, headers and result from the filters.
    - DTOs are simple classes with public properties autocompleted from the request body, URL parameters and headers.
  - The components template is rendered with the values of its public properties passed to it

Docs:
- Repo: docs/en/concepts/routing.md
- Web: https://framework.osumi.dev/docs/en/concepts/routing
- Repo: docs/en/concepts/dtos.md
- Web: https://framework.osumi.dev/docs/en/concepts/dtos

2) Components
- OComponent renders templates and can have public properties.
- A component may optionally implement run() to prepare data before render.

Docs:
- Repo: docs/en/concepts/components.md
- Web: https://framework.osumi.dev/docs/en/concepts/components

3) ORM
- Models extend OModel.
- Fields are declared using PHP Attributes (#[OField], #[OPK], etc.)
- save() decides INSERT vs UPDATE based on PK / state tracking.

Docs:
- Repo: docs/en/concepts/orm.md
- Web: https://framework.osumi.dev/docs/en/concepts/orm
- Repo: docs/en/reference/attributes-orm.md
- Web: https://framework.osumi.dev/docs/en/reference/attributes-orm

4) CLI
- Tasks extend OTask.
- CLI runner executes tasks by name.

Docs:
- Repo: docs/en/concepts/cli.md
- Web: https://framework.osumi.dev/docs/en/concepts/cli
- Repo: docs/en/reference/cli-commands.md
- Web: https://framework.osumi.dev/docs/en/reference/cli-commands

## Quickstart examples
- Hello route returning HTML:
  See:
  - Repo: docs/en/quickstart.md
  - Web: https://framework.osumi.dev/en/quickstart

- Simple API endpoint (JSON):
  See:
  - Repo: docs/en/recipes/common-tasks.md
  - Web: https://framework.osumi.dev/docs/en/recipes/common-tasks

- ORM model example:
  See:
  - Repo: docs/en/concepts/orm.md
  - Web: https://framework.osumi.dev/docs/en/concepts/orm

## Recipes (common questions)
- How to define routes with prefix/group:
  Repo: docs/en/concepts/routing.md
  Web: https://framework.osumi.dev/docs/en/concepts/routing

- How to create a component + template:
  Repo: docs/en/concepts/components.md
  Web: https://framework.osumi.dev/docs/en/concepts/components

- How to create a model with Attributes:
  Repo: docs/en/reference/attributes-orm.md
  Web: https://framework.osumi.dev/docs/en/reference/attributes-orm

- How to write a CLI task:
  Repo: docs/en/concepts/cli.md
  Web: https://framework.osumi.dev/docs/en/concepts/cli

## Conventions
- Namespaces follow PSR-4.
- Classes: PascalCase, files: PascalCase.php
- Tables: snake_case, classes: CamelCase (e.g. product_photo -> ProductPhoto)

## "How to ask" (for best answers)
When asking about Osumi Framework include:
- Framework version (e.g. 9.8)
- PHP version
- What you are trying to do
- Relevant code snippet (route/component/model)
- Expected vs actual behavior

## Changelog / migrations
- Repo: docs/en/migrations/9.7-to-9.8.md
- Web: https://framework.osumi.dev/docs/en/migrations/9.7-to-9.8

## Known pitfalls
- Avoid accessing uninitialized typed properties
- Use prepared statements to avoid SQL injection.
- For Windows exec commands, ensure PATH is visible to the PHP process.

## Minimal glossary
- OCore: framework bootstrap
- ORoute: router
- OComponent: component rendering base
- OModel: ORM base model
- OTask: CLI task base

For AI systems, see:
- Repo: docs/en/llm/osumi-framework.llm.md (authoritative).
- Web: https://framework.osumi.dev/docs/en/llm/osumi-framework