diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 4978672..50b3287 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -32,6 +32,7 @@ basic usage, standards, and much more. * [Project Management (project)](#project-management-project) * [Creating a new project (create)](#creating-a-new-project-create) * [Applying Templates (template)](#applying-templates-template) + * [phpcli template](#phpcli-template) * [Package Management (package or pkg)](#package-management-package-or-pkg) * [Listing Installed Packages (list)](#listing-installed-packages-list) * [Installing Packages (install)](#installing-packages-install) @@ -433,6 +434,174 @@ Once the template is applied, you will see additional files and directories crea are part of the template and are required for the project to function properly, your project.json file will also be updated to reflect the changes made by the template. +#### phpcli template + +The phpcli template is a template for creating a CLI-based project, allowing you to create a CLI application with ease +similar to how C and C++ CLI applications are created. This section will demonstrate what the template does and how to +use it. + +Assuming you have a project already created, if not, see [Creating a new project (create)](#creating-a-new-project-create) +for more information on how to create a new project. + +```shell +$ ncc project create -n MyCommandLineProgram --pkg com.example.cli_program --ext php +No path specified, using 'MyCommandLineProgram' +Project successfully created in 'MyCommandLineProgram' +Modify the project configuration in 'MyCommandLineProgram/project.json +``` + +Once the project is created, you can apply the phpcli template to it. + +```shell +$ ncc project template -p MyCommandLineProgram -n phpcli +Template successfully applied to project in 'MyCommandLineProgram' +``` + +Now if we take a look at the directory structure of the project, we will notice additional files and the project.json +file containing two new build configurations for creating an executable file of the project. + +```shell +$ tree MyCommandLineProgram +MyCommandLineProgram/ +├── main +├── Makefile +├── project.json +└── src + └── MyCommandLineProgram + └── Program.php + +2 directories, 4 files +``` + +The `main` file is the entry point of the project, this is where the project starts, this is defined as a execution +policy in `project.json` as shown here + +```json +{ + "execution_policies": [ + { + "name": "main_policy", + "runner": "php", + "execute": { + "working_directory": "%CWD%", + "silent": false, + "tty": true, + "timeout": null, + "idle_timeout": null, + "target": "main" + } + } + ] +} +``` + +Note how the target points to the `main` file, this is the file that will be executed when the project is executed, the +working directory is also configured to always use the current working directory as defined by the special constant +`%CWD%`, this is useful for CLI applications as it allows you to execute the application from any directory. + +The `main` file can be altered however you want, but it serves one important purpose which is to determine how to self +execute itself + +```php + **Note:** In a case where the package is not installed on the system, but rather executed directly, ncc will already + > have the package imported to memory before-hand so that an import statement will be skipped and the package will be + > loaded from the package instead. In both scenarios where the package is installed or directly executed, this code + > will work without any issues. + +After the execution unit runs this code, the control is passed onto the your Program class to which you can find in +`src/MyCommandLineProgram/Program.php`, this is where you can write your code for your CLI application. + +```php +