static-php-cli/docs/en/develop/structure.md

# Introduction to project structure

static-php-cli mainly contains three logical components: sources, dependent libraries, and extensions.
These components contains 4 configuration files: `source.json`, `pkg.json`, `lib.json`, and `ext.json`.

A complete process for building standalone static PHP is:

1. Use the source download module `Downloader` to download specified or all source codes. 
    These sources include PHP source code, dependent library source code, and extension source code.
2. Use the source decompression module `SourceExtractor` to decompress the downloaded sources to the compilation directory.
3. Use the dependency tool to calculate the dependent extensions and dependent libraries of the currently added extension, 
    and then compile each library that needs to be compiled in the order of dependencies.
4. After building each dependent library using `Builder` under the corresponding operating system, install it to the `buildroot` directory.
5. If external extensions are included (the source code does not contain extensions within PHP), 
    copy the external extensions to the `source/php-src/ext/` directory.
6. Use `Builder` to build the PHP source code and build target to the `buildroot` directory.

The project is mainly divided into several folders:

- `bin/`: used to store program entry files, including `bin/spc`, `bin/spc-alpine-docker`, `bin/setup-runtime`.
- `config/`: Contains all the extensions and dependent libraries supported by the project, 
    as well as the download link and download methods of these sources. It is divided into files: `lib.json`, `ext.json`, `source.json`, `pkg.json`, `pre-built.json` .
- `src/`: The core code of the project, including the entire framework and commands for compiling various extensions and libraries.
- `vendor/`: The directory that Composer depends on, you do not need to make any modifications to it.

The operating principle is to start a `ConsoleApplication` of `symfony/console`, and then parse the commands entered by the user in the terminal.

## Basic command line structure

`bin/spc` is an entry file, including the Unix common `#!/usr/bin/env php`, 
which is used to allow the system to automatically execute with the PHP interpreter installed on the system.
After the project executes `new ConsoleApplication()`, the framework will automatically register them as commands.

The project does not directly use the Command registration method and command execution method recommended by Symfony. Here are small changes:

1. Each command uses the `#[AsCommand()]` Attribute to register the name and description.
2. Abstract `execute()` so that all commands are based on `BaseCommand` (which is based on `Symfony\Component\Console\Command\Command`), 
    and the execution code of each command itself is written in the `handle()` method .
3. Added variable `$no_motd` to `BaseCommand`, which is used to display the Figlet greeting when the command is executed.
4. `BaseCommand` saves `InputInterface` and `OutputInterface` as member variables. You can use `$this->input` and `$this->output` within the command class.

## Basic source code structure

The source code of the project is located in the `src/SPC` directory, 
supports automatic loading of the PSR-4 standard, and contains the following subdirectories and classes:

- `src/SPC/builder/`: The core compilation command code used to build libraries, 
    PHP and related extensions under different operating systems, and also includes some compilation system tool methods.
- `src/SPC/command/`: All commands of the project are here.
- `src/SPC/doctor/`: Doctor module, which is a relatively independent module used to check the system environment. 
    It can be entered using the command `bin/spc doctor`.
- `src/SPC/exception/`: exception class.
- `src/SPC/store/`: Classes related to storage, files and sources are all here.
- `src/SPC/util/`: Some reusable tool methods are here.
- `src/SPC/ConsoleApplication.php`: command line program entry file.

If you have read the source code, you may find that there is also a `src/globals/` directory, 
which is used to store some global variables, global methods, 
and non-PSR-4 standard PHP source code that is relied upon during the build process, such as extension sanity check code etc.

## Phar application directory issue

Like other php-cli projects, spc itself has additional considerations for paths.
Because spc can run in multiple modes such as `php-cli directly`, `micro SAPI`, `php-cli with Phar`, `vendor with Phar`, etc., 
there are ambiguities in various root directories. A complete explanation is given here.
This problem is generally common in the base class path selection problem of accessing files in PHP projects, especially when used with `micro.sfx`.

Note that this may only be useful for you when developing Phar projects or PHP frameworks.

> Next, we will treat `static-php-cli` (that is, spc) as a normal `php` command line program. You can understand spc as any of your own php-cli applications for reference.

There are three basic constant theoretical values below. We recommend that you introduce these three constants when writing PHP projects:

- `WORKING_DIR`: the working directory when executing PHP scripts

- `SOURCE_ROOT_DIR` or `ROOT_DIR`: the root directory of the project folder, generally the directory where `composer.json` is located

- `FRAMEWORK_ROOT_DIR`: the root directory of the framework used, which may be used by self-developed frameworks. Generally, the framework directory is read-only

You can define these constants in your framework entry or cli applications to facilitate the use of paths in your project.

The following are PHP built-in constant values, which have been defined inside the PHP interpreter:

- `__DIR__`: the directory where the file of the currently executed script is located

- `__FILE__`: the file path of the currently executed script

### Git project mode (source)

Git project mode refers to a framework or program itself stored in plain text in the current folder, and running through `php path/to/entry.php`.

Assume that your project is stored in the `/home/example/static-php-cli/` directory, or your project is the framework itself, 
which contains project files such as `composer.json`:

```
composer.json
src/App/MyCommand.app
vendor/*
bin/entry.php
```

We assume that the above constants are obtained from `src/App/MyCommand.php`:

| Constant             | Value                                                |
|----------------------|------------------------------------------------------|
| `WORKING_DIR`        | `/home/example/static-php-cli`                       |
| `SOURCE_ROOT_DIR`    | `/home/example/static-php-cli`                       |
| `FRAMEWORK_ROOT_DIR` | `/home/example/static-php-cli`                       |
| `__DIR__`            | `/home/example/static-php-cli/src/App`               |
| `__FILE__`           | `/home/example/static-php-cli/src/App/MyCommand.php` |

In this case, the values of `WORKING_DIR`, `SOURCE_ROOT_DIR`, and `FRAMEWORK_ROOT_DIR` are exactly the same: `/home/example/static-php-cli`.

The source code of the framework and the source code of the application are both in the current path.

### Vendor library mode (vendor)

The vendor library mode generally means that your project is a framework or is installed into the project as a composer dependency by other applications, 
and the storage location is in the `vendor/author/XXX` directory.

Suppose your project is `crazywhalecc/static-php-cli`, and you or others install this project in another project using `composer require`.

We assume that static-php-cli contains all files except the `vendor` directory with the same `Git mode`, and get the constant value from `src/App/MyCommand`,
Directory constant should be:

| Constant             | Value                                                                                |
|----------------------|--------------------------------------------------------------------------------------|
| `WORKING_DIR`        | `/home/example/another-app`                                                          |
| `SOURCE_ROOT_DIR`    | `/home/example/another-app`                                                          |
| `FRAMEWORK_ROOT_DIR` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli`                       |
| `__DIR__`            | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App`               |
| `__FILE__`           | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |

Here `SOURCE_ROOT_DIR` refers to the root directory of the project using `static-php-cli`.

### Git project Phar mode (source-phar)

Git project Phar mode refers to the mode of packaging the project directory of the Git project mode into a `phar` file. We assume that `/home/example/static-php-cli` will be packaged into a Phar file, and the directory has the following files:

```
composer.json
src/App/MyCommand.app
vendor/*
bin/entry.php
```

When packaged into `app.phar` and stored in the `/home/example/static-php-cli` directory, `app.phar` is executed at this time. Assuming that the `src/App/MyCommand` code is executed, the constant is obtained in the file:

| Constant             | Value                                                                |
|----------------------|----------------------------------------------------------------------|
| `WORKING_DIR`        | `/home/example/static-php-cli`                                       |
| `SOURCE_ROOT_DIR`    | `phar:///home/example/static-php-cli/app.phar/`                      |
| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/static-php-cli/app.phar/`                      |
| `__DIR__`            | `phar:///home/example/static-php-cli/app.phar/src/App`               |
| `__FILE__`           | `phar:///home/example/static-php-cli/app.phar/src/App/MyCommand.php` |

Because the `phar://` protocol is required to read files in the phar itself, the project root directory and the framework directory will be different from `WORKING_DIR`.

### Vendor Library Phar Mode (vendor-phar)

Vendor Library Phar Mode means that your project is installed as a framework in other projects and stored in the `vendor` directory.

We assume that your project directory structure is as follows:

```
composer.json                           # Composer configuration file of the current project
box.json                                # Configuration file for packaging Phar
another-app.php                         # Entry file of another project
vendor/crazywhalecc/static-php-cli/*    # Your project is used as a dependent library
```

When packaging these files under the directory `/home/example/another-app/` into `app.phar`, the value of the following constant for your project should be:

| Constant             | Value                                                                                                |
|----------------------|------------------------------------------------------------------------------------------------------|
| `WORKING_DIR`        | `/home/example/another-app`                                                                          |
| `SOURCE_ROOT_DIR`    | `phar:///home/example/another-app/app.phar/`                                                         |
| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli`                       |
| `__DIR__`            | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App`               |
| `__FILE__`           | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |