CLI (Command Line Interface)

Osumi Framework provides a powerful command-line interface to automate development tasks, manage the database, and run custom scripts. The entry point for all CLI commands is the of file located in the root of your project.

Usage

Commands are executed using PHP from the terminal:

php of <option> [arguments]

If the file is executed without any arguments, the list of available options are shown (both Framework options and user created ones).

Core Commands

The framework includes several built-in tasks:

• add: Create new actions, services, tasks, models, components, or filters.
• generateModel: Create the SQL database schema from your model classes.
• generateModelFrom / generateModelFromDB: Reverse engineering to create models.
• backupAll / backupDB: Create security copies of files and/or database.
• extractor: Export the entire application into a single self-extracting file.
• reset: Clear all non-framework data for a fresh installation.
• version: Display the current framework version.

Custom Tasks

You can extend the CLI by creating your own tasks. Any class placed in src/Task/ that extends OTask will automatically appear as an available option in the of command.

Creating a Task

A task requires two main elements:

1. __toString(): Returns a brief description of the task (displayed in the help menu).
2. run(array $options): The logic to be executed.

Example: AddUserTask.php

<?php declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Task;

use Osumi\OsumiFramework\Core\OTask;
use Osumi\OsumiFramework\App\Model\User;

class AddUserTask extends OTask {
  public function __toString() {
    return "addUser: Task to create new users";
  }

  public function run(array $options=[]): void {
    $name = $options['name'] ?? $options[0] ?? null;

    if (is_null($name)) {
      echo "Error: Name is required.\n";
      return;
    }

    $u = new User();
    $u->name = $name;
    $u->save();

    echo "User " . $name . " created successfully.\n";
  }
}

Handling Arguments

The run method receives an $options array that supports two styles of input:

1. Positional Arguments

Passed directly after the command name.

php of addUser "John Doe"
# $options = [0 => "John Doe"]

2. Named Parameters

Using the --key value syntax. This results in an associative array.

php of addUser --name "John Doe"
# $options = ["name" => "John Doe"]

Note on $options$: The $options parameter is always an array, DTOs can't be used on Tasks.

Task Features

Classes extending OTask have access to several built-in utilities:

• $this->getConfig(): Access application configuration.
• $this->getColors(): Use the OColors utility to output colored text to the console.
• ORM Access: You can use any Model class to perform database operations just as you would in a Component.
• Programmatic Execution: Tasks can be instantiated and run from other parts of the code, not just the terminal.

Best Practices

• Help Messages: Use the run method to check if required arguments are present and display a usage example if they are missing.
• Color Coding: Use $this->getColors()->getColoredString() to highlight errors in red or success messages in green for better UX.
• Namespace: Ensure your custom tasks are under the Osumi\OsumiFramework\App\Task namespace.