PHPAML

Documentation · Chapter 02

Why are there
so many folders?

A project organizes its files like a home organizes its belongings. Let us discover each location without trying to memorize everything.

No prior technical vocabulary is required. Every new word is explained before it is used.

Start with only three areas.

VISIBLEpublic/

What the browser can request directly: the entry point, images, and public files.

YOUR WORKsrc/

The code you write: controllers, models, routes, services, and views.

INSTALLED TOOLSruntime/

Technical elements prepared by AML. You use them, but do not place your pages there.

File, folder, and extension: what is the difference?

A file contains information or code. A folder groups several files. The extension after the dot helps identify the content: .php for PHP code, .css for visual styling, and .json for structured information.

HomeController.php

a PHP code file

home.css

a file describing appearance

phpaml.json

a configuration file read by AML

Other files you will often encounter.

composer.jsonCONFIGURATION

Declares the PHP packages used by the project.

composer.lockVERSIONS

Records exact installed versions so the same environment can be reproduced.

.envLOCAL SECRETS

Contains machine-specific settings. Do not publish it when it contains secrets.

tests/VERIFICATION

Contains code that automatically checks application behavior.

storage/RUNTIME DATA

May contain logs, cache, or files produced while running, depending on the project.

What you edit and what tools manage.

YOU EDIT

src/ · public/ · tests/ · phpaml.json · composer.json

TOOLS GENERALLY MANAGE

runtime/ · composer.lock · cache

This separation does not forbid all advanced changes. It mainly shows where a beginner should work without editing generated files that may later be replaced.

BEGINNER QUESTIONS

You may be wondering…

Should I edit runtime/?

Usually no. AML installs and rebuilds this folder. Your own code mainly lives in src/.

Why is public/ special?

The Web server exposes it to the browser. Secrets and internal code must stay outside it.

Can I create my own folders in src/?

Yes. As the application grows, you can organize services, components, or other responsibilities there.

One file tells AML: “the project starts here.”

This file is named phpaml.json. It contains a few details about the project. The word manifest simply means this identity card. It lets AML find the project even when your terminal is inside a subfolder.

phpaml — zsh
project/
├── phpaml.json        ← la fiche d’identité
├── public/            ← ce que le Web peut voir
├── src/               ← votre code, y compris src/routes/
└── runtime/           ← les outils installés

Where should a new file go?

An image available by URLpublic/
A URL rulesrc/routes/
An HTTP actionsrc/controllers/
A business rule or data objectsrc/models/
A PHP interfacesrc/views/
An installed dependencyruntime/

Apply the map to our library.

phpaml — zsh
public/images/covers/clean-code.jpg
src/routes/WebApp.php
src/controllers/BookController.php
src/models/Book.php
src/views/books/show.php

The cover is public because the browser must download it. The route knows the address. The controller orchestrates the lookup. Book represents the book. The view knows how to display its title and cover. No file performs two jobs.

CHECK YOUR UNDERSTANDING

Why should .env and src/ never be placed under public/?

Show the answer

Because public/ is exposed to the Web server. Secrets and internal code must remain outside that root.

YOUR TURN

Place these files: logo.svg, CheckoutController.php, User.php, WebApp.php, and a rebuildable cache file.

Show a hint

Use public/, src/controllers/, src/models/, src/routes/, and runtime/.

SUMMARY

What to remember

  • public/ is the only Web root.
  • src/ contains your application, including src/routes/.
  • runtime/ can be rebuilt.
  • phpaml.json identifies and describes the project.