PHPAML

MVC tutorial · Chapter 01

Install AML and
create a project.

By the end of this chapter, your environment will be verified and your first PHPAML application will run locally.

Prerequisites

A Windows 10/11, macOS 12+, or Debian/Ubuntu Linux computer, an internet connection, and a terminal. No existing PHP installation is required.

Learning objectives

What you will actually be able to do.

This chapter is not about copying five commands. You will understand what each one prepares, which files belong to you, and how to recognize a healthy environment. That understanding prevents you from deleting the runtime, installing dependencies in the wrong place, or confusing the framework with its command-line tool.

  • Distinguish AML, PHPAML, and the runtime
  • Install and verify the environment
  • Create, start, and diagnose a project
  • Understand the local development cycle

Mental model

Three roles, one workflow.

AML is the tool used in the terminal. PHPAML is the framework that structures and runs the application. The runtime is the private environment assembled by AML. You write the product; AML maintains the machinery required to execute it.

1AML prepares

The command checks the machine, downloads the official template, and creates your application files.

2The runtime executes

The private engine loads the framework, dependencies, and your configuration.

3PHPAML responds

The router finds the controller, builds the response, and sends it to the browser.

Remember

Do not manually edit libraries stored in runtime. An update or a new aml install may rebuild them. Your code, routes, and declarative settings remain outside this private engine.

01.1

AML and PHPAML

PHPAML is the MVC mini-framework. AML is its command-line tool: it installs the environment, creates projects, starts the server, and diagnoses the machine. Once AML is installed, PHP and Composer do not need to be installed separately.

01.2

Install AML

Download the installer for your system from the official page. Windows uses the .exe file, macOS the .pkg package, and Linux the .deb package. The installer adds AML, PHP, and Composer to the machine.

Windows.exe · x64 · 10/11Download ↓macOS.pkg · Apple SiliconDownload ↓Linux.deb · x64 · Debian/UbuntuDownload ↓
01.3

Choose the language

During installation, choose English or Français. This choice controls help, confirmations, and error messages. You can change it later in the AML configuration.

01.4

Check the machine

The doctor command checks AML, PHP, extensions, Composer, temporary folders, cache, and the development port. Resolve every ERROR line before creating your first project.

phpaml — zsh
aml doctor
EXPECTED OUTPUT
phpaml — zsh
[OK]        AML                     version 1.7.0-beta.20
[OK]        PHP                     compatible
[OK]        Private Composer        available
[OK]        Temporary directory     writable
[OK]        Cache AML               writable
[OK]        Development port        127.0.0.1:8910 available
01.5

Create the first project

Create a new folder with aml create my-project, or use aml create . inside an existing empty folder. AML downloads the official template and prepares the MVC structure.

NEW FOLDER
phpaml — zsh
aml create my-first-app
cd my-first-app
aml install
aml serve
EMPTY CURRENT FOLDER
phpaml — zsh
mkdir my-first-app
cd my-first-app
aml create .
aml install
aml serve
01.6

Install and start

aml install installs the private engine in runtime. aml serve then starts the local website with automatic refresh. Keep this terminal open while developing.

EXPECTED OUTPUT
phpaml — zsh
PHPAML development server
→ http://127.0.0.1:8910
Live reload enabled
Local addresshttp://127.0.0.1:8910
01.7

Troubleshoot

If AML does not recognize the project, make sure you are inside the folder containing phpaml.json, src, and runtime. If a port is busy, AML automatically tries the next one. Always run aml doctor again after a fix.

MessageSolution
not a PHPAML projectEnter the correct folder or run aml create .
Address already in useAML automatically tries the next port.
Permission deniedCheck folder permissions, then run doctor again.
GitHub unavailableReuse the cache with aml create project --offline.

Final exercise

Create your first application.

  1. Check the machine with aml doctor.
  2. Create a project named task-app.
  3. Install its dependencies with aml install.
  4. Start it with aml serve and open the local page.
Chapter complete when…✓ aml doctor✓ task-app✓ HTTP 200

Guided solution

Verify the outcome, not only the commands.

doctor must finish without a blocking error. At the root of task-app, phpaml.json must exist: it is the project manifest. After aml install, runtime must exist. Finally, aml serve announces a local address, normally port 8910; when busy, AML tries 8911 and subsequent ports.

Knowledge check

  1. Which tool creates the project: AML or PHPAML?
  2. Why does runtime not contain your business logic?
  3. What should you do after fixing a machine problem?
Show answers

AML creates and maintains the project. PHPAML runs the application. The runtime is replaceable and reserved for the engine. After a fix, run aml doctor again to confirm that the complete environment is healthy.

← All chaptersChapter 02 · PHPAML architecture →